telo3-ai 5.0.7 → 6.2.0

package/references/document-specification.md

@@ -1,425 +1,116 @@
 # Document Specification
+**Load when:** creating, updating, validating, or locating the six project-context documents.
+
+Six documents, non-overlapping responsibilities. The validator (`src/validate.js`) checks required sections by case-insensitive substring match against markdown headings: each required key must appear inside some heading; extra words and any casing are allowed.
+Example: heading "## Recently Completed Work" satisfies key "recently completed work"; "## Security Practices" satisfies "security". Run `telo3 validate [dir] [--json] [--strict]` after edits.
+
+## Ownership
+
+| Doc | Single responsibility | Temporal scope |
+|---|---|---|
+| prd.md | WHAT the product is and WHY it exists | Stable, strategic |
+| architecture.md | HOW the system is built | Stable with evolution |
+| rules.md | HOW to engineer the project | Stable, principles-based |
+| design.md | HOW the product looks and behaves | Stable with refinement |
+| tasks.md | WHAT implementation work remains | Dynamic, short-term |
+| memory.md | CURRENT STATE and continuity | Dynamic |
+
+Information flows prd → architecture → rules → design → tasks → memory. Reference upstream docs; don't restate them.
+
+## Required Sections and Per-Document Rules
+
+### prd.md
+- Required headings: Project Overview; Problem Statement; Target Users; Goals; Functional Requirements; Success Criteria.
+- Holds: vision/strategy; users and use cases; functional requirements; goals and success criteria; scope boundaries (goals/non-goals); product decisions and rationale.
+- Excludes: implementation (architecture.md); coding standards (rules.md); visual design (design.md); status (tasks.md, memory.md).
+- Update when: requirements change/clarify; scope changes; product decisions; success criteria defined/changed; new user insights.
+- Avoid: inventing requirements without user input; technical detail; temporary notes (memory.md); duplicating architecture/design.
+
+### architecture.md
+- Required headings: Architecture Overview; Technology Stack; Project Structure; Architectural Decisions.
+- Holds: stack and dependencies; system structure; data models/relationships; API architecture/conventions; auth flow; external integrations; deployment/infrastructure; decisions and rationale.
+- Excludes: requirements (prd.md); coding standards (rules.md); visual design (design.md); task lists (tasks.md); temporary notes (memory.md).
+- Update when: stack changes; new external services; significant schema changes; API changes; deployment changes; major refactoring; architectural decisions.
+- Avoid: documenting what should exist instead of what does; implementation TODOs (tasks.md); duplicating package-file dependency lists (reference them); coding standards (rules.md).
+
+### rules.md
+- Required headings: Core Principles; Security; Testing; Validation.
+- Holds: coding standards/conventions; file organization; security practices; privacy guidelines; testing requirements; git practices; performance guidelines; accessibility standards; compliance awareness; refactoring principles.
+- Excludes: requirements (prd.md); architecture (architecture.md); visual design (design.md); tasks (tasks.md); current violations/debt (memory.md).
+- Update when: standards established/changed; security practices evolve; new compliance considerations; team quality agreements; accessibility/performance standards change.
+- Avoid: rules nobody follows; over-prescription blocking judgment; duplicating conventions documented elsewhere; implementation-specific notes.
+
+### design.md
+- Required headings: Design Philosophy; Colors; Typography; Components; Accessibility.
+- Holds: philosophy/principles; color system; typography; spacing/layout; component specs; interaction patterns; accessibility guidelines; responsive behavior; animation/motion; anti-patterns.
+- Excludes: features (prd.md); implementation (architecture.md); code organization (rules.md); design tasks (tasks.md); current inconsistencies (memory.md).
+- Update when: brand changes; components standardized; tokens modified; accessibility requirements change; breakpoints change; new anti-patterns identified.
+- Avoid: every component variant; implementation code (reference components); one-off designs; style guide without UX guidance.
+
+### tasks.md
+- Required headings: Current Sprint; Backlog; Completed Recently.
+- Holds: feature backlog; bug list; technical debt; implementation phases; work in progress; recently completed work; blocked tasks.
+- Excludes: requirements (prd.md); architecture (architecture.md); standards (rules.md); design system (design.md); decisions/context (memory.md).
+- Update when: meaningful work completed; backlog additions; reprioritization; bugs found/fixed; debt identified/addressed.
+- Avoid: tracking every tiny change; keeping completed tasks forever (archive); decision rationale (memory.md); duplicating an external bug tracker.
+
+### memory.md
+- Required headings: Current State; Recently Completed Work; Important Decisions; Known Issues.
+- Holds: current status; recent work summaries; decisions that must persist; known bugs/limitations; temporary workarounds; debt context; discoveries; pending questions; project preferences; security/privacy/compliance considerations.
+- Excludes: stable requirements/architecture/rules/design (their docs); detailed task breakdowns (tasks.md); conversation transcripts; secrets/credentials.
+- Update when: significant work done; important decisions; workarounds introduced; bugs/limitations discovered; architecture changes in progress; important context emerges.
+- Avoid: conversation-log format; stable info belonging elsewhere; secrets/sensitive data; outdated entries kept indefinitely; long prose — keep concise and scannable.
+
+## Global Anti-Patterns
+
+- memory.md is NOT a conversation transcript.
+- No duplication across docs: choose the primary home by responsibility and reference it; brief context summaries are acceptable (architecture.md owns "database is PostgreSQL"; rules.md says "see architecture.md; all queries parameterized").
+- No secrets or credentials in any context doc — record that a secret is needed, never its value.
+- Mark unknowns as [UNKNOWN] or [TODO: clarify]; never invent requirements or facts.
+
+## Location
+
+All six files share one location; any of:
+- `project-context/` — dedicated directory.
+- `docs/project-context/` — inside general docs.
+- Project root — simple projects.
+
+Existing docs: don't replace unnecessarily; complement with structure; consolidate only for clear benefit. Reference them, e.g.:
 
-> Detailed specifications for each of the six core project context documents.
-
----
-
-## Overview
-
-The project context system uses six distinct documents with non-overlapping responsibilities:
-
-| Document | Focus | Temporal Scope |
-|----------|-------|----------------|
-| **prd.md** | Requirements & Product | Stable, strategic |
-| **architecture.md** | Technical Structure | Stable with evolution |
-| **rules.md** | Engineering Standards | Stable, principles-based |
-| **design.md** | Visual & UX Patterns | Stable with refinement |
-| **tasks.md** | Implementation Work | Dynamic, short-term |
-| **memory.md** | Current State & Context | Dynamic, continuity |
-
----
-
-## prd.md — Product Requirements Document
-
-### Purpose
-Define **WHAT** the product is and **WHY** it exists.
-
-### Responsibilities
-- Product vision and strategy
-- Target users and use cases
-- Functional requirements
-- Goals and success criteria
-- Scope boundaries (goals and non-goals)
-- Product decisions and rationale
-
-### What NOT to Include
-- ❌ How the system is implemented (that's architecture.md)
-- ❌ Coding standards (that's rules.md)
-- ❌ Visual design (that's design.md)
-- ❌ Current implementation status (that's tasks.md and memory.md)
-
-### When to Update
-- Requirements change or are clarified
-- Scope changes (new goals or non-goals)
-- Important product decisions are made
-- Success criteria are defined or changed
-- New user insights emerge
-
-### Anti-Patterns
-- Inventing requirements without user input
-- Documenting technical implementation details
-- Including temporary notes that belong in memory.md
-- Duplicating architecture or design information
-
----
-
-## architecture.md — Architecture Documentation
-
-### Purpose
-Define **HOW** the system works technically.
-
-### Responsibilities
-- Technology stack and dependencies
-- System structure and organization
-- Data models and relationships
-- API architecture and conventions
-- Authentication and authorization flow
-- External service integrations
-- Deployment and infrastructure
-- Architectural decisions and rationale
-
-### What NOT to Include
-- ❌ Product requirements (that's prd.md)
-- ❌ Coding standards (that's rules.md)
-- ❌ Visual design system (that's design.md)
-- ❌ Implementation task list (that's tasks.md)
-- ❌ Temporary implementation notes (that's memory.md)
-
-### When to Update
-- Technology stack changes
-- New external services are integrated
-- Database schema changes significantly
-- API structure changes
-- Deployment process changes
-- Major architectural refactoring occurs
-- Architectural decisions are made
-
-### Anti-Patterns
-- Documenting what should exist rather than what does exist
-- Including implementation TODOs (use tasks.md)
-- Duplicating dependency lists from package files (reference them instead)
-- Documenting coding standards (use rules.md)
-
----
-
-## rules.md — Engineering Rules
-
-### Purpose
-Define **HOW** the project must be engineered.
-
-### Responsibilities
-- Coding standards and conventions
-- File organization patterns
-- Security practices
-- Privacy guidelines
-- Testing requirements
-- Git and version control practices
-- Performance guidelines
-- Accessibility standards
-- Compliance awareness
-- Refactoring principles
-
-### What NOT to Include
-- ❌ Product requirements (that's prd.md)
-- ❌ System architecture (that's architecture.md)
-- ❌ Visual design standards (that's design.md)
-- ❌ Specific implementation tasks (that's tasks.md)
-- ❌ Current violations or technical debt (that's memory.md)
-
-### When to Update
-- Engineering standards are established or changed
-- Security practices evolve
-- New compliance considerations are identified
-- Team agreements about code quality are made
-- Accessibility or performance standards change
-
-### Anti-Patterns
-- Writing rules that are not actually followed
-- Creating overly prescriptive rules that prevent good judgment
-- Duplicating technology-specific conventions that are documented elsewhere
-- Including implementation-specific notes
-
----
-
-## design.md — Design System
-
-### Purpose
-Define **HOW** the product looks and behaves.
-
-### Responsibilities
-- Design philosophy and principles
-- Color system
-- Typography
-- Spacing and layout
-- Component specifications
-- Interaction patterns
-- Accessibility guidelines
-- Responsive behavior
-- Animation and motion
-- Anti-patterns to avoid
-
-### What NOT to Include
-- ❌ Product features (that's prd.md)
-- ❌ Technical implementation (that's architecture.md)
-- ❌ Code organization (that's rules.md)
-- ❌ Design tasks (that's tasks.md)
-- ❌ Current design inconsistencies (that's memory.md)
-
-### When to Update
-- Brand identity changes
-- New components are standardized
-- Design tokens are modified
-- Accessibility requirements change
-- Responsive breakpoints change
-- Design anti-patterns are identified
-
-### Anti-Patterns
-- Documenting every possible component variant
-- Including implementation code (reference components instead)
-- Documenting one-off designs that aren't patterns
-- Making it a visual style guide without UX guidance
-
----
-
-## tasks.md — Tasks & Implementation Backlog
-
-### Purpose
-Track **WHAT** implementation work remains.
-
-### Responsibilities
-- Feature backlog
-- Bug list
-- Technical debt tracking
-- Implementation phases
-- Active work in progress
-- Recently completed work
-- Blocked tasks
-
-### What NOT to Include
-- ❌ Product requirements (that's prd.md)
-- ❌ Architectural design (that's architecture.md)
-- ❌ Coding standards (that's rules.md)
-- ❌ Design system (that's design.md)
-- ❌ Decisions and context (that's memory.md)
-
-### When to Update
-- After completing meaningful work
-- When adding new features to the backlog
-- When prioritization changes
-- When bugs are discovered or fixed
-- When technical debt is identified or addressed
-
-### Anti-Patterns
-- Tracking every tiny code change
-- Keeping completed tasks indefinitely (archive them)
-- Including decision rationale (use memory.md)
-- Duplicating bug tracker content
-
----
-
-## memory.md — Project Memory
-
-### Purpose
-Track **CURRENT STATE** and important continuity information.
-
-### Responsibilities
-- Current project status
-- Recently completed work (summary)
-- Important decisions that must be preserved
-- Known bugs and limitations
-- Temporary workarounds
-- Technical debt context
-- Important discoveries
-- Pending questions
-- Project-specific preferences
-- Security/privacy/compliance considerations
-
-### What NOT to Include
-- ❌ Stable product requirements (that's prd.md)
-- ❌ Stable architecture (that's architecture.md)
-- ❌ Established engineering rules (that's rules.md)
-- ❌ Established design patterns (that's design.md)
-- ❌ Detailed task breakdowns (that's tasks.md)
-- ❌ Conversation transcripts
-- ❌ Secrets or credentials
-
-### When to Update
-- After significant implementation work
-- When important decisions are made
-- When temporary workarounds are introduced
-- When new bugs or limitations are discovered
-- When architectural changes are in progress
-- When important context emerges
-
-### Anti-Patterns
-- Turning it into a conversation log
-- Documenting stable information that belongs elsewhere
-- Including secrets or sensitive data
-- Keeping outdated information indefinitely
-- Writing novels (keep it concise and scannable)
-
----
-
-## Document Relationships
-
-### Information Flow
-
-```
-Product Strategy (prd.md)
-          ↓
-Technical Design (architecture.md)
-          ↓
-Engineering Standards (rules.md)
-          ↓
-Visual Design (design.md)
-          ↓
-Implementation (tasks.md)
-          ↓
-Current State (memory.md)
-```
-
-### Cross-References
-
-Documents should reference each other when necessary:
-
-- **prd.md** might reference architecture.md for technical constraints
-- **architecture.md** might reference prd.md for product requirements
-- **rules.md** might reference architecture.md for technology-specific standards
-- **design.md** might reference rules.md for accessibility standards
-- **tasks.md** should reference all documents for implementation context
-- **memory.md** might reference any document for context
-
-### Avoiding Duplication
-
-When information logically belongs in multiple documents:
-
-1. **Choose the primary home** based on responsibility
-2. **Reference, don't duplicate** — Link to the primary source
-3. **Exception:** Brief summaries are acceptable for context
-
-Example:
-- **Primary:** architecture.md documents the database is PostgreSQL
-- **Reference:** rules.md might say "See architecture.md for database choice; all queries must use parameterized statements"
-
----
-
-## Document Lifecycle
-
-### Creation
-1. Start with templates
-2. Inspect actual project implementation
-3. Fill in known information
-4. Mark unknowns explicitly
-5. Never invent information
-
-### Maintenance
-1. Update after meaningful changes
-2. Keep information current
-3. Remove outdated information
-4. Archive historical information when appropriate
-5. Maintain clear document history
-
-### Archival
-1. Move completed tasks to "Recently Completed" or remove
-2. Move superseded decisions to "Historical Decisions" or note status
-3. Remove temporary workarounds after they're fixed
-4. Keep information needed for understanding current state
-
----
-
-## Document Location
-
-### Recommended Locations
-
-**Option 1: Dedicated directory**
-```
-project-context/
-├── prd.md
-├── architecture.md
-├── rules.md
-├── design.md
-├── tasks.md
-└── memory.md
 ```
-
-**Option 2: General documentation directory**
-```
-docs/project-context/
-├── prd.md
-├── architecture.md
-├── rules.md
-├── design.md
-├── tasks.md
-└── memory.md
-```
-
-**Option 3: Project root** (for simple projects)
-```
-PROJECT_ROOT/
-├── prd.md
-├── architecture.md
-├── rules.md
-├── design.md
-├── tasks.md
-└── memory.md
-```
-
-### Integration with Existing Documentation
-
-If the project already has documentation:
-- **Don't replace** existing docs unnecessarily
-- **Reference** existing docs from context documents
-- **Complement** existing docs with structure
-- **Consolidate** only if there's clear benefit
-
-Example integration in architecture.md:
-```markdown
 ## Additional Documentation
-
-- API documentation: See `/docs/api/README.md`
-- Database schema: See `/docs/schema.md`
-- Deployment guide: See `DEPLOY.md`
+- API docs: /docs/api/README.md
+- Schema: /docs/schema.md
+- Deploy guide: DEPLOY.md
 ```
 
----
-
-## Validation
-
-### Quality Checks
-
-Each document should be:
-- ✅ **Clear:** Easy to understand
-- ✅ **Current:** Reflects actual state
-- ✅ **Concise:** No unnecessary verbosity
-- ✅ **Complete:** Covers its responsibilities
-- ✅ **Consistent:** Aligned with other documents
-- ✅ **Actionable:** Provides useful guidance
-
-### Common Issues
-
-- ❌ **Stale information:** Document says X, code does Y
-- ❌ **Missing information:** Key decisions not documented
-- ❌ **Duplicated information:** Same thing in multiple places
-- ❌ **Wrong document:** Information in the wrong place
-- ❌ **Too detailed:** Documenting every implementation detail
-- ❌ **Too vague:** Not providing useful guidance
-
----
-
-## Success Criteria
-
-The six-document system is working well when:
-
-✅ AI agents understand the project before coding  
-✅ New developers can onboard from the documents  
-✅ Decisions are documented and preserved  
-✅ Architectural drift is prevented  
-✅ Design consistency is maintained  
-✅ Important context is not lost  
-✅ Documentation stays synchronized with code  
-✅ Team members reference the docs regularly  
-
----
-
-## Summary
-
-| Document | Question | Update Frequency |
-|----------|----------|------------------|
-| prd.md | What & Why? | Quarterly or when requirements change |
-| architecture.md | How is it built? | When architecture changes |
-| rules.md | How should we code? | When standards evolve |
-| design.md | How should it look? | When design patterns change |
-| tasks.md | What needs to be done? | Weekly or after significant work |
-| memory.md | What's the current state? | After important work or decisions |
-
-**Remember:** These are living documents. Keep them current, concise, and useful.
+## Templates and Lifecycle
+
+- Templates are lean starting skeletons (~50–80 lines), not 400-line questionnaires. Grow sections only as the project needs.
+- Create: start from template → inspect actual implementation → fill known information → mark unknowns → never invent.
+- Maintain: update after meaningful changes; keep current; remove stale info; archive history when appropriate; keep docs synchronized with code.
+- Archive: completed tasks → "Completed Recently" or remove; superseded decisions → historical section or status note; remove workarounds once fixed; keep what explains current state.
+
+## Update Cadence
+
+| Doc | Typical frequency |
+|---|---|
+| prd.md | Quarterly or when requirements change |
+| architecture.md | When architecture changes |
+| rules.md | When standards evolve |
+| design.md | When design patterns change |
+| tasks.md | Weekly or after significant work |
+| memory.md | After important work or decisions |
+
+## Cross-References and Quality
+
+- Cross-reference when needed: prd↔architecture (constraints/requirements); rules→architecture (tech-specific standards); design→rules (accessibility); tasks→any doc; memory→any doc.
+- Each doc must be: clear, current (matches code), concise, complete for its responsibility, consistent with other docs, actionable.
+- Common failures:
+  - Stale info — doc says X, code does Y.
+  - Missing info — key decisions undocumented.
+  - Duplicated info — same content in multiple docs.
+  - Wrong doc — info outside its responsibility.
+  - Too detailed — every implementation detail captured.
+  - Too vague — no useful guidance.
+- System works when: agents understand the project before coding; newcomers can onboard from docs; decisions persist; architectural drift and design inconsistency are prevented; context is never lost; docs stay synchronized with code.