ace-docs 0.31.0

data/handbook/templates/project-docs/blueprint.template.md

@@ -0,0 +1,165 @@
+---
+doc-type: template
+title: "Project Blueprint: [Project Name]"
+purpose: Documentation for ace-docs/handbook/templates/project-docs/blueprint.template.md
+ace-docs:
+  last-updated: 2026-01-10
+  last-checked: 2026-03-21
+---
+
+# Project Blueprint: [Project Name]
+
+## What is a Blueprint?
+
+This document provides a concise overview of the project's structure and organization, highlighting key directories and files to help developers (especially AI assistants) quickly understand how to navigate the codebase. It should be updated periodically using the `update-blueprint` workflow.
+
+## Core Project Documents
+
+- [What We Build](docs/vision.md) - Project vision and goals
+- [Architecture](docs/architecture.md) - System design and implementation principles
+- [Blueprint](docs/blueprint.md) - Project structure and organization
+
+## Project Organization
+
+<!-- Describe your project's main directory structure -->
+
+This project follows a documentation-first approach with these primary directories:
+
+- **handbook/** - Package-specific development resources and workflows
+  - **guides/** - Best practices and standards for development
+  - **tools/** - Utility scripts to support development workflows
+  - **workflow-instructions/** - Structured commands for AI agents
+  - **zed/** - Editor integration (if applicable)
+
+- **dev-taskflow/** - Project-specific documentation
+  - **current/** - Active release cycle work
+  - **backlog/** - Pending tasks for future releases
+  - **done/** - Completed releases and tasks
+  - **decisions/** - Architecture Decision Records (ADRs)
+
+- **bin/** - Executable scripts for project management and automation
+
+- **src/** - Source code (adjust directory names as needed)
+  - **[component1]/** - Core functionality
+  - **[component2]/** - Additional features
+  - **utils/** - Shared utilities
+
+- **tests/** - Test files and test utilities
+
+- **config/** - Configuration files
+
+<!-- Add your project-specific directories here -->
+
+## View Complete Directory Structure
+
+To see the complete filtered directory structure, run:
+
+```bash
+task-manager recentee
+```
+
+This will show all project files while filtering out temporary files, session logs, and other non-essential directories.
+
+## Key Project-Specific Files
+
+<!-- List important files that developers should know about -->
+
+- [Workflow Instructions](wfi://README) - Entry point for understanding available AI workflows
+- [Project Guides](guide://README) - Development standards and best practices
+- [Configuration](README.md) - Configuration documentation (if applicable)
+
+## Technology Stack
+
+<!-- Summarize the main technologies used -->
+
+- **Primary Language**: [e.g., JavaScript, Python, Rust]
+- **Framework**: [e.g., React, Django, Axum]
+- **Database**: [e.g., PostgreSQL, MongoDB, SQLite]
+- **Key Libraries**: [List important dependencies]
+- **Development Tools**: [e.g., Docker, Webpack, Cargo]
+
+## Read-Only Paths
+
+This section lists files and directories that the agent should treat as read-only. Attempts to modify these paths should be flagged or prevented.
+
+<!-- Add project-specific read-only paths -->
+- `docs/decisions/**/*`
+- `dev-taskflow/done/**/*`
+- `*.lock` # Dependency lock files
+- `dist/**/*` # Built artifacts
+- `build/**/*` # Build output
+
+## Ignored Paths
+
+This section lists files, directories, or glob patterns that the agent should ignore entirely during its operations (e.g., when searching, reading, or editing files).
+
+- `dev-taskflow/done/**/*` # Default: Protects completed tasks and releases
+- `**/node_modules/**`
+- `**/.git/**`
+- `**/__pycache__/**`
+- `**/target/**` # Rust build artifacts
+- `**/dist/**` # Built distributions
+- `**/build/**` # Build artifacts
+- `**/.env` # Environment files
+- `**/.env.*` # Environment variants
+- `*.session.log`
+- `*.lock`
+- `*.tmp`
+- `*~` # Backup files
+- `**/.DS_Store` # macOS system files
+- `**/Thumbs.db` # Windows system files
+
+## Entry Points
+
+<!-- Document the main ways to start or interact with the project -->
+
+### Development
+
+```bash
+# Start development server
+bin/run
+
+# Run tests
+# Run project-specific test command
+
+# Build for production
+bin/build
+```
+
+### Common Workflows
+
+- **New Feature**: Use `task-manager next` to find next task, follow task workflow
+- **Bug Fix**: Create task in backlog, prioritize, implement
+- **Documentation**: Update relevant files in `dev-taskflow/`
+
+## Dependencies
+
+<!-- List major external dependencies and their purposes -->
+
+### Runtime Dependencies
+
+- [Library 1]: Purpose and version constraints
+- [Library 2]: Purpose and version constraints
+
+### Development Dependencies
+
+## Submodules
+
+<!-- Document any Git submodules used -->
+
+### docs-dev (if applicable)
+
+- Path: `docs-dev`
+- Repository: [Repository URL]
+- Purpose: Development workflows and guides
+- **Important**: Commits for this submodule must be made from within the submodule directory
+
+### [Other Submodules]
+
+- Path: `[path]`
+- Repository: [Repository URL]
+- Purpose: [Description]
+
+---
+
+*This blueprint should be updated when significant structural changes are made to the project. Use the `update-blueprint` workflow to keep it current.*

data/handbook/templates/project-docs/context/ownership.yml

@@ -0,0 +1,160 @@
+# Document Ownership & Responsibility Model
+# This file defines what content belongs in each documentation file
+# Used by context tool and update-context-docs workflow for validation
+
+version: 1.0
+description: |
+  Defines ownership boundaries for project documentation.
+  Each topic should appear in exactly ONE document.
+  Other documents should reference, not duplicate.
+
+# Topic definitions - what each topic category means
+topics:
+  # Vision & Business Topics
+  project_vision:
+    description: "Mission, goals, what we're building and why"
+    keywords: [vision, mission, goal, objective, purpose]
+    
+  user_personas:
+    description: "Target users, their needs, pain points, jobs to be done"
+    keywords: [persona, user, customer, audience, needs]
+    
+  business_value:
+    description: "Value proposition, ROI, problems solved, market opportunity"
+    keywords: [value, proposition, advantage, benefit, problem]
+    
+  feature_list_user_facing:
+    description: "High-level features from user perspective (what, not how)"
+    keywords: [feature, capability, functionality, offering]
+
+  # Technical Topics
+  technology_stack:
+    description: "Languages, frameworks, libraries, tools, and versions"
+    keywords: [framework, library, language, tool, version, dependency]
+    
+  system_design:
+    description: "Architecture patterns, component design, data flow, integrations"
+    keywords: [architecture, pattern, design, component, integration]
+    
+  development_patterns:
+    description: "Code conventions, best practices, principles, guidelines"
+    keywords: [convention, practice, principle, guideline, standard]
+    
+  technical_dependencies:
+    description: "Package dependencies, external services, version requirements"
+    keywords: [dependency, package, requirement, service]
+
+  # Structure Topics  
+  directory_structure:
+    description: "Folder organization, project layout, file tree"
+    keywords: [folder, directory, structure, tree, organization]
+    
+  file_organization:
+    description: "Where specific types of files live, naming conventions"
+    keywords: [file, location, path, organization]
+    
+  entry_points:
+    description: "Main files, how to start/build/deploy, quick commands"
+    keywords: [entry, start, build, deploy, command]
+
+  # Design Topics
+  visual_design:
+    description: "Color palette, typography, spacing, layout principles"
+    keywords: [color, typography, spacing, layout, design]
+    
+  component_styles:
+    description: "UI component appearance, CSS classes, styling rules"
+    keywords: [style, css, class, component, appearance]
+    
+  brand_guidelines:
+    description: "Logo usage, tone of voice, visual identity, brand rules"
+    keywords: [brand, logo, identity, tone, guideline]
+
+  # Tool Topics
+  tool_documentation:
+    description: "How to use development tools, CLI commands, utilities"
+    keywords: [tool, command, cli, utility, usage]
+    
+  command_reference:
+    description: "Command syntax, flags, options, parameters"
+    keywords: [command, flag, option, parameter, syntax]
+    
+  usage_examples:
+    description: "Sample workflows, common patterns, recipes"
+    keywords: [example, workflow, pattern, recipe, sample]
+
+# Document ownership - what each file owns and must not contain
+documents:
+  docs/vision.md:
+    owns:
+      - project_vision
+      - user_personas
+      - business_value
+      - feature_list_user_facing
+    must_not_contain:
+      - technology_stack
+      - system_design
+      - directory_structure
+      - technical_dependencies
+      - command_reference
+    cross_references:
+      - "For technical details → architecture.md"
+      - "For project structure → blueprint.md"
+
+  docs/architecture.md:
+    owns:
+      - technology_stack
+      - system_design
+      - development_patterns
+      - technical_dependencies
+    must_not_contain:
+      - project_vision
+      - user_personas
+      - directory_structure
+      - command_reference
+      - brand_guidelines
+    cross_references:
+      - "For project goals → vision.md"
+      - "For file structure → blueprint.md"
+      - "For commands → tools.md"
+
+  docs/blueprint.md:
+    owns:
+      - directory_structure
+      - file_organization
+      - entry_points
+    must_not_contain:
+      - technology_stack  # (rationale belongs in architecture)
+      - system_design
+      - project_vision
+      - development_patterns
+      - tool_documentation  # (details belong in tools.md)
+    cross_references:
+      - "For technology choices → architecture.md"
+      - "For tool details → tools.md"
+
+  docs/tools.md:
+    owns:
+      - tool_documentation
+      - command_reference
+      - usage_examples
+    must_not_contain:
+      - project_vision
+      - system_design
+      - visual_design
+    cross_references:
+      - "For architecture → architecture.md"
+      - "For project info → vision.md"
+
+  docs/styles.md:
+    owns:
+      - visual_design
+      - component_styles
+      - brand_guidelines
+    must_not_contain:
+      - technology_stack
+      - system_design
+      - project_vision
+      - directory_structure
+    cross_references:
+      - "For technical implementation → architecture.md"

data/handbook/templates/project-docs/decisions/adr.template.md

@@ -0,0 +1,60 @@
+---
+doc-type: template
+title: "ADR-XXX: Title of the Decision"
+purpose: Documentation for ace-docs/handbook/templates/project-docs/decisions/adr.template.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# ADR-XXX: Title of the Decision
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded]
+Date: YYYY-MM-DD
+
+## Context
+
+What is the issue that we're seeing that is motivating this decision or change?
+
+## Decision
+
+What is the change that we're proposing and/or doing?
+
+## Consequences
+
+What becomes easier or more difficult to do because of this change?
+
+### Positive
+
+- Benefit 1
+- Benefit 2
+
+### Negative
+
+- Challenge 1
+- Challenge 2
+
+### Neutral
+
+- Impact 1
+- Impact 2
+
+## Alternatives Considered
+
+- Alternative 1
+  - Why it wasn't chosen
+- Alternative 2
+  - Why it wasn't chosen
+
+## Related Decisions
+
+- Link to related ADRs
+- Link to related documentation
+
+## References
+
+- External references
+- Research papers
+- Blog posts

data/handbook/templates/project-docs/prd.template.md

@@ -0,0 +1,144 @@
+---
+doc-type: template
+title: Product Requirements Document (PRD) Template
+purpose: Documentation for ace-docs/handbook/templates/project-docs/prd.template.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Product Requirements Document (PRD) Template
+
+## Project Overview
+
+### Problem Statement
+<!-- Describe the core problem this project aims to solve -->
+
+### Proposed Solution
+<!-- High-level description of your approach to solving the problem -->
+
+### Success Metrics
+<!-- How will you measure success? Include quantifiable goals where possible -->
+
+## Project Details
+
+### Project Name
+<!-- The official name of your project -->
+
+### Target Audience
+<!-- Who are the primary users/beneficiaries of this project? -->
+
+### Core Value Proposition
+<!-- What unique value does this project provide? -->
+
+## Functional Requirements
+
+### Must-Have Features (P0)
+<!-- Critical features without which the project cannot succeed -->
+- [ ] Feature 1: Description
+- [ ] Feature 2: Description
+
+### Should-Have Features (P1)
+<!-- Important features that significantly enhance the project -->
+- [ ] Feature 1: Description
+- [ ] Feature 2: Description
+
+### Could-Have Features (P2)
+<!-- Nice-to-have features for future consideration -->
+- [ ] Feature 1: Description
+- [ ] Feature 2: Description
+
+## Technical Considerations
+
+### Technology Stack
+<!-- Preferred programming languages, frameworks, databases, etc. -->
+- **Primary Language**:
+- **Framework/Runtime**:
+- **Database**:
+- **Key Libraries**:
+- **Deployment**:
+
+### Architecture Requirements
+<!-- High-level architectural constraints or preferences -->
+
+### Performance Requirements
+<!-- Speed, scalability, and resource constraints -->
+
+### Security Requirements
+<!-- Security considerations and compliance needs -->
+
+### Integration Requirements
+<!-- External systems or APIs this project needs to work with -->
+
+## User Stories
+
+### Primary User Flows
+<!-- Describe the main user journeys through your application -->
+
+#### User Story 1
+
+**As a** [type of user]  
+**I want** [goal/desire]  
+**So that** [benefit/value]
+
+**Acceptance Criteria:**
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+#### User Story 2
+
+**As a** [type of user]  
+**I want** [goal/desire]  
+**So that** [benefit/value]
+
+**Acceptance Criteria:**
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Implementation Timeline
+
+### Phase 1: Foundation (Estimated: X weeks)
+<!-- Core functionality and basic features -->
+
+### Phase 2: Enhancement (Estimated: X weeks)  
+<!-- Additional features and improvements -->
+
+### Phase 3: Polish (Estimated: X weeks)
+<!-- Testing, optimization, documentation -->
+
+## Dependencies and Risks
+
+### External Dependencies
+<!-- Third-party services, libraries, or resources you depend on -->
+
+### Risk Assessment
+<!-- Potential challenges and mitigation strategies -->
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|-------------------|
+| Risk 1 | High/Medium/Low | High/Medium/Low | Strategy description |
+
+## Out of Scope
+
+### Explicitly Excluded Features
+<!-- Features that might be expected but are intentionally not included -->
+
+### Future Considerations
+<!-- Features or improvements for potential future phases -->
+
+## Approval and Sign-off
+
+### Stakeholders
+<!-- List key stakeholders who need to approve this PRD -->
+
+### Approval Status
+
+- [ ] Technical Lead Approval
+- [ ] Product Owner Approval
+- [ ] Architecture Review Complete
+- [ ] Ready for Implementation
+
+---
+
+*This PRD should be reviewed and updated as the project evolves. Version control and change tracking should be maintained for all modifications.*

data/handbook/templates/project-docs/roadmap/roadmap.template.md

@@ -0,0 +1,47 @@
+---
+doc-type: template
+title: Project Roadmap
+purpose: Documentation for ace-docs/handbook/templates/project-docs/roadmap/roadmap.template.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Project Roadmap
+
+## 1. Project Vision
+
+[Inspirational statement describing the long-term mission and value the project brings to users. Keep concise (1-3 sentences) and focused on outcomes rather than technical details.]
+
+## 2. Strategic Objectives
+
+| # | Objective | Success Metric |
+|---|-----------|----------------|
+| 1 | [Outcome-focused objective] | [Measurable criteria] |
+| 2 | [Outcome-focused objective] | [Measurable criteria] |
+
+## 3. Key Themes & Epics
+
+| Theme | Description | Linked Epics |
+|-------|-------------|-------------|
+| [Theme Name] | [Brief description of theme purpose] | [Epic identifiers] |
+| [Theme Name] | [Brief description of theme purpose] | [Epic identifiers] |
+
+## 4. Planned Major Releases
+
+| Version | Codename | Target Window | Goals | Key Epics |
+|---------|----------|---------------|-------|-----------|
+| v.X.Y.Z | "[Name]" | QX YYYY | [Primary goals] | [Related epics] |
+| v.X.Y.Z | "[Name]" | QX YYYY | [Primary goals] | [Related epics] |
+
+## 5. Cross-Release Dependencies
+
+- [Dependency description linking specific epics/releases]
+- [Dependency description linking specific epics/releases]
+
+## 6. Update History
+
+| Date | Summary | Author |
+|------|---------|--------|
+| YYYY-MM-DD | [Brief change description] | [Author name] |
+| YYYY-MM-DD | Initial roadmap creation | [Author name] |