Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
26 Commits 2 Branches 0 Tags
197f44b4d358b8c9fee52d299c783c0fb2671578
Commit Graph

6 Commits

Author SHA1 Message Date
Gitea Actions
197f44b4d3 docs: add issues capture system and KB documentation
Some checks failed
KB Lint / validate (push) Has been cancelled
Details 
This commit adds the issues capture system from PAIRS project and documents
it in the KB system, following all KB system rules for changelog and index
updates.

## What Was Added

### 1. Issues Capture System (docs/issues/)

**docs/issues/README.md** - System documentation:
- Purpose and workflow for quick issue capture
- File naming convention (YYYY-MM-DD--short-description.md)
- Issue types (bug, feature, insight, structural, improvement, question)
- Template fields and best practices
- Integration with Gitea platform
- Future automation possibilities

**docs/issues/template.md** - Issue file template:
- Minimal required fields (title, type, date, status)
- Optional fields (description, impact, notes, related)
- Gitea issue tracking section
- Simple, quick-capture format

**docs/issues/2025-11-11--gitea-runner-setup-request.md** - Moved from .github/:
- Gitea Actions runner configuration request
- Updated to match issue template format
- Includes type, date, status fields
- Ready for compilation to Gitea issue

### 2. KB Documentation Entry

**kb/02_systems/2025-11-11--issues-capture-system--note.md** - KB entry:
- Documents the issues capture system structure and workflow
- Explains quick capture process
- Describes compilation to Gitea issues
- Includes best practices and integration points
- Properly categorized in 02_systems/ (infrastructure/tooling)
- Complete frontmatter with all 18 required fields

### 3. KB System Updates

**kb/CHANGELOG.md** - Updated:
- Added entry for issues capture system documentation
- Date: 2025-11-11
- Documents KB file addition

**kb/_index.md** - Regenerated:
- Index updated via generate-index.sh script
- New KB file appears in 02_systems category
- Topics indexed: documentation, issue-tracking, workflow, gitea
- Tags indexed: issues, capture, documentation, gitea, workflow
- Summary updated with file count

## Why This Implementation

### Quick Issue Capture
   The issues capture system provides a lightweight staging area for capturing
   issues, insights, bugs, and features as you encounter them. This enables
   quick capture without the overhead of creating formal Gitea issues immediately.

### Markdown-Based Workflow
   Issues are captured as markdown files, making them easy to edit, version
   control, and review. This provides flexibility before committing to formal
   issue tracking.

### Later Compilation
   Issues can be batch-processed into Gitea issues when ready, allowing for
   review, prioritization, and grouping before creating formal issues.

### Documentation in KB
   The issues capture system is documented in the KB system, making it
   discoverable and providing reference material for the workflow.

## Technical Details

### File Structure

### Issue File Format

- **Naming**:
- **Template**: Minimal fields for quick capture
- **Status**: captured → reviewed → compiled
- **Integration**: Links to Gitea issues when compiled

### KB Entry Details

- **Category**: 02_systems (infrastructure, DevOps, tooling)
- **Type**: note
- **Topics**: documentation, issue-tracking, workflow, gitea
- **Tags**: issues, capture, documentation, gitea, workflow
- **Routing Confidence**: 0.95 (high confidence)

## Files Added/Modified

### Added
- docs/issues/README.md - Issues capture system documentation
- docs/issues/template.md - Issue file template
- docs/issues/2025-11-11--gitea-runner-setup-request.md - Runner setup request (moved from .github/)
- kb/02_systems/2025-11-11--issues-capture-system--note.md - KB documentation entry

### Modified
- kb/CHANGELOG.md - Added entry for new KB file
- kb/_index.md - Regenerated with new KB file indexed

## KB System Compliance

✅ KB file follows naming convention (YYYY-MM-DD--slug--type.md)
✅ KB file has complete frontmatter (all 18 required fields)
✅ KB file date matches filename date
✅ KB file type matches filename type
✅ KB changelog updated with entry
✅ KB index regenerated via script
✅ All changes committed together

## Related

- Source: PAIRS-for-the-Individual project (docs/issues/)
- KB System: kb/README.md
- KB Changelog: kb/CHANGELOG.md
- KB Index: kb/_index.md
- Gitea Documentation: docs/GITEA/
 2025-11-11 12:31:15 -07:00
Gitea Actions
3ad53162c8 test(kb): add temporary test file for workflow validation
Some checks failed
KB Lint / validate (push) Has been cancelled
Details 
This is a temporary test file to validate the KB lint workflow.
The file follows all KB rules and should pass validation.
Will be deleted after workflow testing is complete.
 2025-11-11 11:55:12 -07:00
Gitea Actions
830629f105 chore: update KB index [skip ci] 2025-11-11 11:53:12 -07:00
Data Warrior
db003786f9 docs(phases): add Phase 3-6 plans and update Phase 2 plan 
This commit adds comprehensive plan documents for all remaining phases
of the project setup system replication:

## Phase Plans Added

### Phase 2 Plan (Updated)
- KB System Setup plan document
- Already implemented in previous commit
- Plan document now tracked in repository

### Phase 3 Plan (New)
- Gitea Actions Workflows Setup
- Covers .github/ documentation and workflow creation
- KB lint and KB index update workflows
- Customized for Tendril and Gitea platform

### Phase 4 Plan (New)
- LLM Usage Guides Setup
- LLM-Usage-Guide.md and Prompt-Creation-Guide.md
- Initial prompt documents
- Customized for Tendril project

### Phase 5 Plan (New)
- Validation and Testing
- Comprehensive testing procedures
- Test scenarios for all system components
- Troubleshooting guide

### Phase 6 Plan (New)
- Customization and Final Verification
- Project name and terminology verification
- Directory structure verification
- Final documentation review
- System integration verification

## Plan Structure

All plans follow consistent structure:
- Overview and current state
- Detailed task breakdown
- Customizations for Tendril
- Files to create
- Dependencies and success criteria
- Validation checklists
- Notes and references

## Customizations

All plans are customized for:
- Tendril project (not "pairs")
- Gitea platform (not GitHub)
- Tendril-specific directory structure
- Gitea Actions (with GitHub Actions compatibility notes)

## Files Added

- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-2-PLAN.md (5.0KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-3-PLAN.md (13KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md (8.1KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-5-PLAN.md (12KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-6-PLAN.md (11KB)

Total: 5 phase plan documents, ~49KB of planning documentation
 2025-11-11 11:50:01 -07:00
Data Warrior
aecc370e1d docs(kb): implement Phase 2 KB System Setup 
This commit implements the complete Knowledge Base (KB) system for the Tendril
project, establishing a structured, LLM-friendly system for capturing and
organizing external information that informs project development.

## What Was Implemented

### 1. KB System Documentation (kb/README.md)
   - Comprehensive documentation explaining the KB system's purpose and structure
   - Directory structure explanation with all 8 category directories
   - File naming schema: YYYY-MM-DD--slug--type.md with regex validation
   - Complete frontmatter schema documentation (18 required fields for Tendril)
   - Routing decision tree for categorizing content
   - Routing confidence system (0.00-1.00 scale) with policy for low-confidence items
   - Usage guidelines for creating and managing KB files
   - Integration notes with phase documentation system
   - Index generation and changelog update procedures

### 2. KB File Templates (kb/_templates/)
   Created three template files with complete frontmatter:

   - note.md: General notes template with draft status default
   - decision.md: ADR-style decision template with active status default
   - howto.md: How-to guide template with active status default

   All templates include:
   - All 18 required frontmatter fields (base + Tendril-specific)
   - Placeholder syntax (${VARIABLE}) for easy customization
   - Appropriate default values (routing_confidence, status, etc.)
   - Template-specific content sections
   - Customized for Tendril project (project: ["tendril"])

### 3. KB Ingestion Prompt (kb/_guides/KB_INGEST_PROMPT.md)
   Complete system prompt for LLM-assisted KB ingestion:

   - System instructions for content analysis and routing
   - Classification and routing rules for all 8 categories
   - Routing decision tree with 9-step decision process
   - Routing confidence assessment guidelines
   - File naming standards with examples and validation
   - Complete frontmatter requirements documentation
   - JSON output format specification
   - Quality and style guidelines
   - Safety constraints (NEVER/ALWAYS rules)
   - Validation checklist
   - Completion summary format with mandatory index/changelog updates

### 4. Index Generation Script (kb/scripts/generate-index.sh)
   Bash script for automatic KB index generation:

   - Scans all KB files in category directories (01_projects through 08_archive)
   - Excludes special directories (_guides, _templates, _inbox, _review_queue)
   - Extracts YAML frontmatter from each KB file
   - Parses metadata fields (title, date, type, summary, topics, tags, phases)
   - Generates kb/_index.md with:
     * File listing organized by category
     * Topics index (all unique topics with file references)
     * Tags index (all unique tags with file references)
     * Phase relevance index (files organized by phase)
     * Summary statistics
   - Compatible with Windows (Git Bash) and Unix systems
   - Uses temporary files for cross-platform compatibility
   - Handles errors gracefully (missing frontmatter, invalid files)
   - Script is executable (chmod +x)

### 5. KB Changelog (kb/CHANGELOG.md)
   Change tracking for KB system:

   - Initial entry documenting Phase 2 setup
   - Date-based format: ## [YYYY-MM-DD] KB System Setup
   - Lists all files created during setup
   - Notes about customization for Tendril project

### 6. Initial Index (kb/_index.md)
   Auto-generated searchable index:

   - Generated by running generate-index.sh
   - Currently empty (no KB files exist yet)
   - Ready to be populated as KB files are added
   - Includes proper structure for all index sections

## Why This Implementation

### Structured Knowledge Capture
   The KB system provides a lightweight staging area for external information
   (Pulse Daily chats, ideas, notes, research) that may inform Tendril project
   development. Unlike formal phase documentation, KB entries capture informal
   knowledge that complements the structured phase blueprints.

### LLM-Friendly Design
   The system is designed for LLM-assisted ingestion and management:
   - Clear routing decision tree enables automated classification
   - Confidence scoring allows human review of uncertain routing
   - Complete frontmatter ensures rich metadata for searchability
   - JSON output format enables automated file creation

### Searchability and Discovery
   The automatic index generation creates multiple access paths:
   - By category (for browsing related content)
   - By topic (for finding content on specific subjects)
   - By tag (for cross-cutting categorization)
   - By phase relevance (for finding content related to specific phases)

### Integration with Phase Documentation
   KB decisions complement phase-specific ADRs, KB research informs phase
   planning, and KB playbooks provide operational guides. The phase_relevance
   field creates explicit links between KB content and project phases.

### Project Customization
   All files are customized for Tendril:
   - Project name: "tendril" (replaced "pairs" references)
   - Default project field: ["tendril"]
   - Path references updated for Tendril structure
   - Gitea Actions noted (not GitHub Actions) for Phase 3

## Technical Details

### Frontmatter Schema (18 Fields)
   Base fields (14): title, date, author, source, project, topics, tags, type,
   status, routing_hint, proposed_path, routing_confidence, related, summary

   Tendril-specific (4): captured_at, source_type, related_projects,
   phase_relevance

   Optional (2): key_takeaways, action_candidates

### File Naming Pattern
   Regex: ^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$

   Components: Date (YYYY-MM-DD) + Slug (3-8 words, no stop-words) + Type

### Routing Confidence Policy
   - >= 0.60: File goes to proposed_path
   - < 0.60: File goes to _review_queue/ (with proposed_path in frontmatter)

## Next Steps

Phase 2 complete. Ready for Phase 3: Gitea Actions Workflows configuration.

## Files Added

- kb/README.md (290 lines)
- kb/_templates/note.md
- kb/_templates/decision.md
- kb/_templates/howto.md
- kb/_guides/KB_INGEST_PROMPT.md (~400 lines)
- kb/scripts/generate-index.sh (executable)
- kb/CHANGELOG.md
- kb/_index.md (auto-generated)
 2025-11-11 11:43:52 -07:00
Data Warrior
03db6efeb8 docs: reorganize project structure and add Gitea platform context 
This commit implements a comprehensive reorganization of project documentation
and adds explicit Gitea platform context throughout the project.

## Documentation Reorganization

### File Moves (Content Preserved)
- Moved CURSOR_WINDOWS_SETUP.md to kb/_guides/ for better organization
- Moved docs/PHASE-UPDATES/ to kb/_guides/PROJECT-SETUP-GUIDE/:
  - COMPLETE-SYSTEM-REPLICATION-GUIDE.md
  - PHASE-0-GITEA-UPDATES.md
  - README.md
- Added new file: kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md

**Reason**: Consolidate project setup and configuration guides into the
knowledge base structure for better discoverability and organization.

### New Phase Documentation Structure
Created tendril/phases/ directory with structured phase documentation:
- phase-00-foundation/: blueprint, changelog, decisions, tasks
- phase-01-testing-validation/: blueprint, changelog, decisions, tasks

**Reason**: Establish consistent phase documentation structure following
project guidelines for phase management and tracking.

## Gitea Platform Context Integration

### .cursorrules Updates
- Added comprehensive Gitea platform context section
- Added Gitea documentation references for workflows and platform questions
- Added platform terminology guidelines (Gitea vs GitHub)
- Added references to docs/GITEA/ documentation throughout rules

**Reason**: Ensure all AI agents and contributors use correct Gitea terminology
and have clear guidance on where to find Gitea-specific documentation.

### Documentation Path Updates
- CONTRIBUTING.md: Updated CURSOR_WINDOWS_SETUP.md path reference
- docs/AGENT-GUIDELINES.md: Updated path references to moved documentation
- PROJECT_STATUS.md: Updated comment to mention Gitea Actions

**Reason**: Maintain link integrity after file reorganization and ensure
documentation references point to correct locations.

## Impact and Benefits

1. **Better Organization**: Documentation is now organized in logical
   structures (kb/ for knowledge base, tendril/phases/ for phase docs)

2. **Clear Platform Context**: Explicit Gitea platform references prevent
   confusion with GitHub terminology and provide clear documentation paths

3. **Consistent Structure**: Phase documentation follows standardized format
   (blueprint, changelog, decisions, tasks) for easier maintenance

4. **Improved Discoverability**: Guides consolidated in kb/_guides/ make it
   easier to find setup and configuration information

All file moves preserve content - no information was lost in this reorganization.
 2025-11-11 11:38:44 -07:00