@namch/agent-assistant 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] - 2026-03-26
+
+### Changed
+- **Documentation Workflows — Folder-Based Architecture**: Migrated all 3 `/docs` sub-command workflows from single-file to folder-based structure for greater detail and maintainability
+  - **`/docs:core` (v3.0)**: 5 knowledge folders, each with `00-index.md` + numbered sub-files. Added MIGRATE mode for legacy flat-file-to-folder conversion, Thinking Protocol (7-question pre-write checklist), Anti-Shallow Guardrails, and Mode Detection table with per-folder CREATE/UPDATE/MIGRATE resolution
+  - **`/docs:business` (v4.0)**: 4 business folders with folder-based structure. Added MIGRATE mode, Thinking Protocol (5-question checklist), Anti-Shallow Guardrails, and Business Evidence Ledger
+  - **`/docs:audit` (v4.0)**: 4 audit folders with folder-based structure. Added MIGRATE mode, Thinking Protocol (5-question security-focused checklist), and Signal Precision Rules
+  - **`/docs` router (v2.0)**: Updated sequential execution flow references to match new folder-based deliverables and corrected version references
+- **Cross-Workflow Consistency**: Harmonized agent roles (`docs-manager` for generation phase), mode rules (CREATE/UPDATE/MIGRATE), quality mechanisms (Thinking Protocol, Evidence Ledger), and exit criteria across all 3 workflows
+
 ## [1.3.0] - 2026-03-23
 
 ### Added
@@ -90,7 +100,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Blueprint**: `documents/SMART-SKILL-ORCHESTRATION-BLUEPRINT.md` — architecture for dynamic skill resolution
   - **Assessment**: `documents/HSOL-ASSESSMENT.md` — production readiness evaluation
   - **Manifest**: `matrix-skills/_dynamic.yaml` — tracking for dynamically installed community skills
-  - **Knowledge base**: Updated `documents/knowledge-architecture.md`, `documents/knowledge-source-base.md` with HSOL references
+  - **Knowledge base**: Updated `documents/knowledge-architecture/` folder, `documents/knowledge-source-base/` folder with HSOL references
 
 ### Changed
 

package/agents/backend-engineer.md

@@ -60,9 +60,9 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-standards.md → Coding standards
-   - knowledge-architecture.md → Architecture patterns
-   - knowledge-domain.md → Data models, API contracts
+   - knowledge-standards/00-index.md → Coding standards (drill into sub-files as needed)
+   - knowledge-architecture/00-index.md → Architecture patterns (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → Data models, API contracts (drill into sub-files as needed)
    → USE these as constraints for implementation
 
 2. CHECK: ./reports/{topic}/plans/PLAN-{feature} exists?

package/agents/brainstormer.md

@@ -61,9 +61,9 @@ ALWAYS:
 
 ```
 CHECK PROJECT DOCS (if ./documents/ exists):
-- knowledge-overview.md → Project scope
-- business/business-prd.md → Existing requirements
-- business/business-features.md → Existing features
+- knowledge-overview/00-index.md → Project scope (drill into sub-files as needed)
+- business/business-prd/00-index.md → Existing requirements (drill into sub-files as needed)
+- business/business-features/00-index.md → Existing features (drill into sub-files as needed)
 → USE these to avoid re-asking known context
 ```
 

package/agents/business-analyst.md

@@ -61,9 +61,9 @@ ALWAYS:
 
 ```
 CHECK PROJECT DOCS (if ./documents/ exists):
-- business/business-prd.md → Existing PRD
-- business/business-features.md → Feature list
-- business/business-workflows.md → User workflows
+- business/business-prd/00-index.md → Existing PRD (drill into sub-files as needed)
+- business/business-features/00-index.md → Feature list (drill into sub-files as needed)
+- business/business-workflows/00-index.md → User workflows (drill into sub-files as needed)
 → BUILD ON existing docs, don't start from scratch
 ```
 

package/agents/database-architect.md

@@ -61,9 +61,9 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-architecture.md → Existing architecture
-   - knowledge-domain.md → Data models, schema
-   - knowledge-standards.md → Naming conventions
+   - knowledge-architecture/00-index.md → Existing architecture (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → Data models, schema (drill into sub-files as needed)
+   - knowledge-standards/00-index.md → Naming conventions (drill into sub-files as needed)
    → USE these for schema naming and structure
 
 2. CHECK: ./reports/{topic}/plans/PLAN-{feature}

package/agents/debugger.md

@@ -61,8 +61,8 @@ ALWAYS:
 
 ```
 CHECK PROJECT DOCS (if bug involves domain logic):
-- knowledge-architecture.md → System understanding
-- knowledge-domain.md → Expected behavior
+- knowledge-architecture/00-index.md → System understanding (drill into sub-files as needed)
+- knowledge-domain/00-index.md → Expected behavior (drill into sub-files as needed)
 → USE these to understand what SHOULD happen
 ```
 

package/agents/designer.md

@@ -61,8 +61,8 @@ ALWAYS:
 
 ```
 CHECK PROJECT DOCS (if ./documents/ exists):
-- knowledge-standards.md → Design standards
-- business/business-workflows.md → User flows
+- knowledge-standards/00-index.md → Design standards (drill into sub-files as needed)
+- business/business-workflows/00-index.md → User flows (drill into sub-files as needed)
 → USE these for design decisions
 ```
 

package/agents/devops-engineer.md

@@ -61,8 +61,8 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-architecture.md → Infrastructure patterns
-   - knowledge-standards.md → Deployment standards
+   - knowledge-architecture/00-index.md → Infrastructure patterns (drill into sub-files as needed)
+   - knowledge-standards/00-index.md → Deployment standards (drill into sub-files as needed)
    → FOLLOW existing infra conventions
 
 2. CHECK: ./reports/{topic}/plans/PLAN-{feature}

package/agents/docs-manager.md

@@ -62,29 +62,37 @@ ALWAYS:
 
 ```
 CHECK EXISTING PROJECT DOCS (./documents/):
-- knowledge-overview.md → Project overview
-- knowledge-architecture.md → Architecture docs
-- knowledge-domain.md → Data models, API contracts
-- knowledge-standards.md → Coding standards
-→ UPDATE existing docs rather than creating new
+
+FOLDER-BASED (v2.0 — preferred):
+- knowledge-overview/00-index.md     → Project overview + sub-files
+- knowledge-architecture/00-index.md → Architecture docs + sub-files
+- knowledge-domain/00-index.md       → Data models, API contracts + sub-files
+- knowledge-source-base/00-index.md  → Source base + sub-files
+- knowledge-standards/00-index.md    → Coding standards + sub-files
+→ UPDATE existing sub-files; add new sub-files if needed
 ```
 
 ### Step 1: DOCUMENTATION SCOPE
 
-| Type         | Purpose              | Audience       |
-| ------------ | -------------------- | -------------- |
-| README       | Overview, quick start| New users/devs |
-| API Docs     | Endpoint reference   | Developers     |
-| Architecture | System design        | Team           |
-| Guides       | How-to               | Various        |
+| Type         | Purpose              | Audience       | Structure      |
+| ------------ | -------------------- | -------------- | -------------- |
+| README       | Overview, quick start| New users/devs | Single file    |
+| Knowledge    | AI-consumable docs   | AI agents/devs | Folder + sub-files |
+| API Docs     | Endpoint reference   | Developers     | Sub-file in domain/ |
+| Architecture | System design        | Team           | Folder + sub-files |
+| Guides       | How-to               | Various        | Single file    |
+
+**Folder-based docs pattern**: Each knowledge area = folder with `00-index.md` (TOC) + numbered sub-files (`01-*.md`, `02-*.md`, ...).
 
 ### Step 2: DOCUMENTATION AUDIT
 
 - [ ] README exists and current
-- [ ] API endpoints documented
-- [ ] Setup instructions work
-- [ ] Environment variables listed
-- [ ] Architecture documented
+- [ ] Knowledge folders exist with 00-index.md + sub-files
+- [ ] API endpoints documented (in knowledge-domain/03-api-contracts.md)
+- [ ] Setup instructions work (in knowledge-overview/04-getting-started.md)
+- [ ] Environment variables listed (in knowledge-source-base/04-configuration.md)
+- [ ] Architecture documented (in knowledge-architecture/ folder)
+- [ ] All 00-index.md files have accurate sub-file TOC
 
 ### Step 3: DOCUMENTATION PRINCIPLES
 

package/agents/frontend-engineer.md

@@ -60,9 +60,9 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-standards.md → Coding standards
-   - knowledge-architecture.md → Component patterns
-   - knowledge-domain.md → API contracts, data shapes
+   - knowledge-standards/00-index.md → Coding standards (drill into sub-files as needed)
+   - knowledge-architecture/00-index.md → Component patterns (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → API contracts, data shapes (drill into sub-files as needed)
    → USE these as constraints
 
 2. CHECK for:

package/agents/game-engineer.md

@@ -61,9 +61,9 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-standards.md → Coding standards
-   - knowledge-architecture.md → Game architecture
-   - knowledge-domain.md → Game data models
+   - knowledge-standards/00-index.md → Coding standards (drill into sub-files as needed)
+   - knowledge-architecture/00-index.md → Game architecture (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → Game data models (drill into sub-files as needed)
    → USE these for implementation decisions
 
 2. IF plan exists: READ → FOLLOW specifications EXACTLY

package/agents/mobile-engineer.md

@@ -61,10 +61,10 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-standards.md → Coding standards
-   - knowledge-architecture.md → App architecture
-   - knowledge-domain.md → API contracts, data shapes
-   → USE these for implementation decisions
+   - knowledge-standards/00-index.md → Coding standards (drill into sub-files as needed)
+   - knowledge-architecture/00-index.md → App architecture (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → API contracts, data shapes (drill into sub-files as needed)
+   → USE these as constraints for implementation
 
 2. IF plan exists: READ → FOLLOW EXACTLY
 3. IF no plan + complex: STOP → Request plan

package/agents/performance-engineer.md

@@ -61,9 +61,9 @@ ALWAYS:
 
 ```
 CHECK PROJECT DOCS (if ./documents/ exists):
-- knowledge-standards.md → Performance budgets
-- knowledge-architecture.md → System architecture
-- knowledge-domain.md → Data flows, API surface
+- knowledge-standards/00-index.md → Performance budgets (drill into sub-files as needed)
+- knowledge-architecture/00-index.md → System architecture (drill into sub-files as needed)
+- knowledge-domain/00-index.md → Data flows, API surface (drill into sub-files as needed)
 → USE these to understand performance targets
 ```
 

package/agents/planner.md

@@ -82,10 +82,10 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (CRITICAL):
-   - knowledge-overview.md → Project scope
-   - knowledge-architecture.md → Existing architecture
-   - knowledge-domain.md → Data models, API contracts
-   - knowledge-standards.md → Standards to enforce
+   - knowledge-overview/00-index.md → Project scope (drill into sub-files as needed)
+   - knowledge-architecture/00-index.md → Existing architecture (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → Data models, API contracts (drill into sub-files as needed)
+   - knowledge-standards/00-index.md → Standards to enforce (drill into sub-files as needed)
    → INCORPORATE into plan constraints
 
 2. CHECK for prior deliverables:

package/agents/project-manager.md

@@ -61,9 +61,9 @@ ALWAYS:
 
 ```
 CHECK PROJECT DOCS (if ./documents/ exists):
-- knowledge-overview.md → Project scope
-- knowledge-domain.md → Data/API scope
-- business/business-prd.md → Requirements
+- knowledge-overview/00-index.md → Project scope (drill into sub-files as needed)
+- knowledge-domain/00-index.md → Data/API scope (drill into sub-files as needed)
+- business/business-prd/00-index.md → Requirements (drill into sub-files as needed)
 → USE these for project tracking and scope management
 ```
 

package/agents/researcher.md

@@ -61,9 +61,9 @@ ALWAYS:
 
 ```
 CHECK PROJECT DOCS (if ./documents/ exists):
-- knowledge-overview.md → Project context
-- knowledge-architecture.md → Technical context
-- knowledge-domain.md → Domain concepts
+- knowledge-overview/00-index.md → Project context (drill into sub-files as needed)
+- knowledge-architecture/00-index.md → Technical context (drill into sub-files as needed)
+- knowledge-domain/00-index.md → Domain concepts (drill into sub-files as needed)
 → USE these to focus research on project needs
 ```
 

package/agents/reviewer.md

@@ -61,9 +61,9 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-standards.md → Standards to enforce
-   - knowledge-architecture.md → Architecture to verify
-   - knowledge-domain.md → Data/API contracts to verify
+   - knowledge-standards/00-index.md → Standards to enforce (drill into sub-files as needed)
+   - knowledge-architecture/00-index.md → Architecture to verify (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → Data/API contracts to verify (drill into sub-files as needed)
    → VERIFY code follows project standards
 
 2. IF ./reports/{topic}/plans/PLAN-{feature} exists:

package/agents/scouter.md

@@ -61,9 +61,9 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-architecture.md → Already documented architecture
-   - knowledge-domain.md → Data models, API contracts
-   - knowledge-standards.md → Existing standards
+   - knowledge-architecture/00-index.md → Already documented architecture (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → Data models, API contracts (drill into sub-files as needed)
+   - knowledge-standards/00-index.md → Existing standards (drill into sub-files as needed)
    → REFERENCE these, don't duplicate findings
 
 2. Your output becomes CONSTRAINTS for downstream agents

package/agents/security-engineer.md

@@ -62,9 +62,9 @@ ALWAYS:
 
 ```
 CHECK PROJECT DOCS (if ./documents/ exists):
-- knowledge-standards.md → Security standards
-- knowledge-architecture.md → Attack surface
-- knowledge-domain.md → API surface, auth boundaries
+- knowledge-standards/00-index.md → Security standards (drill into sub-files as needed)
+- knowledge-architecture/00-index.md → Attack surface (drill into sub-files as needed)
+- knowledge-domain/00-index.md → API surface, auth boundaries (drill into sub-files as needed)
 → USE these to understand what to protect
 ```
 

package/agents/tech-lead.md

@@ -60,9 +60,9 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-standards.md → Enforce these
-   - knowledge-architecture.md → Architecture constraints
-   - knowledge-domain.md → Data/API constraints
+   - knowledge-standards/00-index.md → Enforce these (drill into sub-files as needed)
+   - knowledge-architecture/00-index.md → Architecture constraints (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → Data/API constraints (drill into sub-files as needed)
    → VERIFY all work aligns with project standards
 
 2. IF ./reports/{topic}/plans/PLAN-{feature} exists:

package/agents/tester.md

@@ -60,8 +60,8 @@ ALWAYS:
 
 ```
 1. CHECK PROJECT DOCS (if ./documents/ exists):
-   - knowledge-standards.md → Testing standards
-   - knowledge-domain.md → Data shapes, API contracts
+   - knowledge-standards/00-index.md → Testing standards (drill into sub-files as needed)
+   - knowledge-domain/00-index.md → Data shapes, API contracts (drill into sub-files as needed)
    → USE these for test fixtures/assertions
 
 2. IF ./reports/{topic}/plans/PLAN-{feature} exists: