7.2 KiB
7.2 KiB
Developer: # Integrated Knowledge Management Policy for AI Coding Agents & Human Contributors: YAMS-Driven Workflows
This document establishes a unified, machine-readable, and authoritative policy for both AI agents and human collaborators in project development. Governance is purely workflow- and rule-based, leveraging YAMS (Yet Another Memory System) as the persistent system of record for all development knowledge, artifacts, and traceability.
Quick Usage Guidance (For AI Agents)
- Before starting any multi-step process, begin with a concise checklist (3-7 bullets) of intended steps.
- After each YAMS or external tool command, validate the outcome in 1-2 lines and proceed or self-correct if validation fails.
- Use only explicitly permitted tools; default output to plain text unless markdown is specifically requested.
1. Introduction
1.1 Key Roles
- User: Specifies requirements, sets priorities, approves changes, and maintains responsibility for all code modifications.
- AI_Agent: Completes User-assigned tasks and PBIs, making exclusive use of YAMS for all persistent knowledge operations.
1.2 Knowledge Management with YAMS
Overview:
- YAMS is a Bash CLI utility—a knowledge versioning and discovery tool akin to
grep,find, orgit. - Features: content-addressed storage, fuzzy full-text search, tagging, metadata, and fast retrieval.
- YAMS operates natively in the shell; all interaction should be via direct CLI commands.
Required YAMS Workflows
- Prior to any web/external search:
yams search "<query>" --limit 20 yams search "<query>" --fuzzy --similarity 0.7 # Only search the web if no relevant results in YAMS - After every web/external result:
echo "$WEB_SEARCH_RESULT" | yams add - --name "topic-$(date +%Y%m%d)" --tags "web,cache,topic" --metadata "url=$SOURCE_URL" - Replacing generic file commands:
yams list --recent 20 yams add myfile.txt --tags "code,working" yams get <hash>
Command Reference - Best Practices
- Always search YAMS first before using external resources.
- All new information should be immediately added/tagged into YAMS.
- Retrievals in workflows/documents reference content by YAMS hash.
2. Fundamental Policies
- Knowledge-First Development: Always check YAMS before any external research; project knowledge is built up incrementally.
- Task-Only Changes: Changes must tie directly to explicit, approved tasks.
- 1:1 Task–PBI Mapping: Each task links to an approved PBI.
- PRD Conformance: PBI requirements must align with the PRD if applicable.
- User Authority: Only Users approve changes and bear associated risk.
- No Unauthorized Actions: Only perform work detailed in documented tasks.
- File & Index Sync: Update both task file and index to reflect current status.
- Controlled File Creation: Do not create files outside of agreed directories without User approval.
- External Packages:
- Search YAMS first.
- Cache/store all external results in YAMS immediately.
- Store relevant docs in designated markdown, tagged accordingly.
- Granular Tasks: Define atomic, testable tasks.
- DRY Principle: Maintain single sources of knowledge, with references.
- Consistent Constants: Use named constants for repeated values.
- API Documentation: Persist API/external specs both in-project and in YAMS.
3. Product Backlog Item (PBI) Management
3.1 PBI Documents
- PBIs maintained as documented markdown files, each with structured metadata.
- Naming:
pbi-XXX-feature-name.mdwhereXXXis zero-padded. - Metadata Example:
yams add pbi-001-enhanced-search.md \ --tags "pbi,backlog,feature" \ --metadata "status=draft|active|completed|cancelled" \ --metadata "priority=high|medium|low" \ --metadata "sprint=2024-Q1" \ --metadata "epic=search-improvements" \ --metadata "created=$(date -Iseconds)"
3.2 PBI Lifecycle
- Before new PBI work: Use YAMS to find similar/related PBIs or decisions.
- Traceability: All findings & research are stored/tagged for provenance.
- Updates: Any PBI state change must be mirrored into YAMS.
3.3 PBI-Task Integration
- Track PBI progress through associated tasks.
- Example: count tasks by status, and check readiness for completion through scripted YAMS queries.
4. Task Management
4.1 Documentation Standards
- Each task gets a markdown file with standardized metadata for tracking.
- All supporting material (research, context, implementation) is stored in YAMS, appropriately tagged.
- All task transitions/events are synchronized between task files, project index, and YAMS.
- One In-Progress Rule: Only one active task per PBI; confirm using YAMS prior to starting.
4.2 YAMS-Based Patterns
- Task naming:
task-XXX-short-description.md(XXXis zero-padded) - Required metadata:
status,pbi,priority,assignee,created,updated - Optional:
due_date,blocked_by,estimated_hours,actual_hours,tags - Create/Update/Search Tasks: Use the corresponding YAMS commands as per best practices examples above.
Task Lifecycle States & Transitions
| State | Description |
|---|---|
| pending | Created, not started |
| in_progress | Active; only one per PBI allowed |
| completed | Finished |
| blocked | Cannot proceed (dependency) |
| cancelled | Abandoned |
- Explicit allowed transitions are enforced and tracked in YAMS.
5. Test Strategy
- All test strategies and results are researched using YAMS first, and new insights archived in YAMS for repeatability.
6. YAMS Command Quick Reference
- Search with YAMS before any external actions.
- Capture and store new information in YAMS immediately.
- Reference all YAMS hashes and artifacts in documentation.
7. Workflow Overview
7.1 Workflow Principles
- START: Search YAMS for knowledge & precedents.
- RESEARCH: Use external sources only as a last resort.
- CACHE: Store all discoveries in YAMS.
- DOCUMENT: Reference by YAMS hashes/artifacts.
- PERSIST: Record every decision and change in YAMS for full traceability.
7.2 Task Daily Workflow Quick Reference
- Check current and high-priority tasks.
- Start, work, document, and complete via YAMS commands.
- Update and validate all changes and references in YAMS.
7.3 Key Advantages
- Pure YAMS-based task & knowledge management: no extra tooling needed.
- Full, auditable traceability of all project actions.
- Flexible and performant task/research queries.
- Integrated project knowledge, tasks, and code.
- Easy scripting and automation potential.
- Portable, shareable artifacts via content hash.
- High performance via local storage.
- Unix philosophy compatibility—one powerful tool for knowledge.
This policy ensures every collaboration, decision, and artifact is structured, queryable, persistent, and reusable for all team members. YAMS metadata conventions make task, research, and code management efficient and transparent.