@laitszkin/apollo-toolkit 3.8.2 → 3.8.4

package/CHANGELOG.md

@@ -22,11 +22,24 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - Simplify `generate-spec` coordination.md to three sections (Business Goals, Design Principles, Spec Boundaries) and restructure preparation.md to follow tasks.md-style compact format
 
+## [v3.8.3] - 2026-05-03
+
+### Changed
+- Refactor `align-project-documents` to generate standardized `docs/features/` (BDD user-facing scenarios), `docs/architecture/` (macro-level design principles), and `docs/principles/` (code conventions and development constraints) instead of flexible Diataxis-based classification
+- Simplify `maintain-project-constraints` to produce `AGENTS.md`/`CLAUDE.md` with exactly three sections: Common Development Commands, Project Business Goals, and Project Documentation Index
+- Update `archive-specs` to delegate documentation generation to the refactored `align-project-documents` and constraint-file refresh to `maintain-project-constraints`; replace flat-category reference templates with the new three-category structure
+
 ## [Unreleased]
 
 ### Added
 - (None yet)
 
+## [v3.8.4] - 2026-05-04
+
+### Changed
+- Simplify `generate-spec` checklist template from 108 lines to 53 lines: consolidate multi-field behavior-to-test items into single-line checkboxes, flatten hardening records, and streamline E2E/integration decisions and completion records
+- Emphasize official documentation lookup as mandatory step in `generate-spec` workflow
+
 ## [v3.8.0] - 2026-04-30
 
 ### Added

package/align-project-documents/SKILL.md

@@ -1,152 +1,158 @@
 ---
 name: align-project-documents
-description: Read and understand a software project, then generate or align project documentation with the current codebase. Use when a user asks for project docs (usage, technical architecture, debugging flow, setup, operations) or asks to verify and sync existing documentation with real implementation.
+description: Read the entire codebase, then generate standardized project documentation under docs/features/, docs/architecture/, and docs/principles/ from code evidence. Remove old documentation that does not conform to the template structure, then refresh AGENTS.md/CLAUDE.md via maintain-project-constraints.
 ---
 
 # Align Project Documents
 
+## Dependencies
+
+- Required: `maintain-project-constraints` to refresh `AGENTS.md/CLAUDE.md` after documentation changes.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
 ## Standards
 
-- Evidence: Treat source code, configuration, scripts, and tests as the source of truth.
-- Execution: Discover project facts before choosing generate mode or align mode.
-- Quality: Keep every non-trivial claim traceable, choose document categories based on actual content, and remove stale documentation instead of appending around it.
-- Output: Write newcomer-friendly docs with descriptive headings, runnable commands, and clear reader guidance.
+- Evidence: Treat source code, configuration, scripts, and tests as the sole source of truth.
+- Execution: Read the entire codebase before writing any documentation; ground every claim in concrete file paths.
+- Quality: Remove outdated documentation that does not conform to the template structure; never leave mixed documentation formats in place.
+- Output: Produce standardized, maintainable documentation organized into three categories: features, architecture, and principles.
 
 ## Goal
 
-Produce accurate, code-grounded project documentation that remains readable for people who do not yet understand the project, its domain, or the development workflow. Prefer evidence from source code, configs, scripts, and tests over assumptions.
+Generate a complete, code-grounded project documentation set under `docs/` that describes what the system does from a user perspective (features), how it is designed (architecture), and what conventions govern its code (principles).
+
+## Target Documentation Structure
+
+```
+docs/
+├── features/       — BDD-described user-facing capabilities, categorized by functional area
+├── architecture/   — macro-level design principles, organized by module or layer
+└── principles/     — code style, naming conventions, dependency management, and development constraints
+```
+
+### docs/features/
+
+- Describe what the system does from a user's perspective.
+- Never reference specific code paths, file names, or implementation details.
+- Use BDD (Behavior-Driven Development) phrasing: "Given ... When ... Then ...".
+- Group features by functional category; each category gets its own markdown file.
+- File titles must clearly convey which functional area or module they cover.
+
+Example feature description:
+
+```markdown
+# 用戶認證與授權
+
+## 登入
+
+- **Given** 用戶擁有有效的帳號密碼
+- **When** 用戶提交登入表單
+- **Then** 系統驗證憑證並返回存取令牌，用戶進入主頁面
+```
+
+### docs/architecture/
+
+- Extract macro-level design principles from the codebase.
+- Group principles by module or architectural layer; each module gets its own markdown file.
+- Every principle must be sufficiently abstract to avoid becoming stale after minor code changes.
+- Focus on module responsibilities, boundary rules, data flow direction, and integration contracts — not on specific implementation details.
+
+Example architecture principle:
+
+```markdown
+# API 層設計原則
+
+## 路由與處理器分離
+
+路由定義與請求處理邏輯存放在不同模組中。路由層只負責 URL 映射與中介軟體綁定，
+處理器層負責請求解析、業務邏輯調用與回應組裝。
+```
+
+### docs/principles/
+
+- Extract code style, naming conventions, and development constraints from the codebase.
+- Categorize into separate markdown files (e.g., naming conventions, dependency management, error handling patterns).
+- Each principle must be traceable to concrete examples in the codebase.
+
+Example principle:
+
+```markdown
+# 命名約定
+
+## 檔案命名
+
+- TypeScript 模組檔案使用 kebab-case：`user-service.ts`
+- React 元件檔案使用 PascalCase：`UserProfile.tsx`
+- 測試檔案與被測檔案同名，加上 `.test` 後綴：`user-service.test.ts`
+```
 
 ## Workflow
 
-### 1) Discover project facts first
-
-- Read key files before writing: `README*`, `package.json`/`pyproject.toml`/`go.mod`, lock files, CI configs, entrypoints, and test setup.
-- Inspect main runtime paths (API/server, worker, frontend, CLI, jobs) and dependency boundaries.
-- Build a factual map: startup commands, environment variables, request/data flow, major modules, external integrations, and observability points.
-- Record concrete evidence with file paths for every important claim.
-- Identify likely readers and their knowledge gaps: new developer, operator, support teammate, product stakeholder, or mixed audience.
-- Identify the actual reader tasks: understand the project, run locally, configure credentials, operate a workflow, debug failures, or change code safely.
-
-### 2) Classify documentation by content, not by fixed headings
-
-- Start from the repository's real content and the readers' jobs to be done.
-- Choose only the categories that are supported by evidence and useful to the target audience.
-- Use open source documentation conventions as the classification baseline instead of inventing project-local categories first.
-- Prefer the Diataxis content families for content classification: tutorial, how-to, reference, and explanation.
-- Map those content families onto common open source document types when appropriate: `README`, `CONTRIBUTING`, `SECURITY`, `CODE_OF_CONDUCT`, troubleshooting guides, glossary, and release/change documents.
-- Prefer descriptive, task-led headings such as `本地啟動 API 服務`, `設定 GitHub OAuth 憑證`, or `匯入任務卡住時如何排查`.
-- Do not force a fixed chapter list when the project does not need it.
-- Use `references/templates/category-based-project-docs-template.md` as the primary selection guide.
-
-Useful content categories include:
-
-- README or docs index for orientation
-- tutorial or getting-started guide for first success
-- how-to or runbook guides for real tasks
-- reference docs for configuration, commands, endpoints, and limits
-- explanation docs for architecture, concepts, and tradeoffs
-- CONTRIBUTING for contribution workflow
-- SECURITY for vulnerability reporting and support policy
-- CODE_OF_CONDUCT for community expectations
-- glossary, FAQ, decisions, or release notes when repository evidence shows they are needed
-
-### 3) Decide documentation mode
-
-- **Generate mode**: no usable docs exist, or user asks to create docs from scratch.
-- **Align mode**: existing docs exist and must be checked against implementation.
-
-### 4) Generate mode output
-
-Create or update a minimal document set chosen from the content categories above. Do not require every project to have the same headings or files.
-
-At minimum, ensure the final output answers the questions that matter for the repository's real readers:
-
-1. What is this project for?
-2. Who usually needs this document?
-3. How do I complete the most common task safely?
-4. What must I prepare before I start?
-5. What result should I expect if things are working?
-6. What usually goes wrong and how do I verify it?
-7. Where in the repository is the source of truth?
-
-Recommended output pattern:
-
-- A short root `README.md` or equivalent entry document for orientation.
-- One or more focused documents grouped by standard documentation type.
-- Optional runbooks for task-heavy or failure-heavy workflows.
-- Optional glossary/FAQ material only when the project actually contains domain complexity or repeated team confusion.
-- Separate contributor or community-governance docs only when the repository exposes those collaboration workflows.
-
-Writing rules:
-
-- Write what is true now, not what should be true.
-- Use concrete commands and paths from the repository.
-- Keep examples executable when possible.
-- Call out unknowns explicitly instead of guessing.
-- Explain why a file, service, command, or environment matters before telling the reader to use it.
-- Assume the reader may not understand local jargon, deployment assumptions, or the project's business terms.
-- Prefer task-oriented section titles over generic labels.
-- Keep different documentation intents separate: tutorials teach, how-to guides solve tasks, reference catalogs facts, and explanation pages provide understanding.
-
-### 5) Align mode output
-
-When docs already exist:
-
-1. Enumerate existing docs and their scope.
-2. Compare each claim against current code and scripts.
-3. Classify findings:
-   - **Accurate**
-   - **Outdated**
-   - **Missing**
-   - **Ambiguous**
-4. Update docs to match real behavior.
-5. Add a short "Documentation Delta" summary listing major corrections.
-6. Rewrite headings that are too generic or template-like so they reflect the real task or concept being documented.
-
-Alignment checklist:
-
-- Startup/install commands still work.
-- Directory/module names match current tree.
-- API/routes/events/messages match implementation.
-- Config keys and env vars match code usage.
-- Debug instructions reference real logs, metrics, and breakpoints.
-- Test commands and expected outputs are current.
-- Headings match actual content categories instead of forcing one universal structure.
-- Newcomers can infer what each document is for before reading the full content.
-- Document placement follows recognizable open source conventions whenever the repository scope justifies them.
-
-### 6) Newcomer-readability rules
-
-- Start each document by making the reader's situation explicit: who this is for, what they are trying to do, and when they should use this document.
-- When describing a task, include prerequisites, exact steps, expected signals, and common failure recovery.
-- When describing architecture, explain responsibilities and boundaries in plain language before diving into paths or modules.
-- When describing configuration or credentials, explain why each key or service exists and what breaks if it is missing.
-- When describing debugging, structure content around observable symptoms and verification paths, not abstract subsystem names.
-- If the repository contains specialist domain language, add a glossary or inline definitions instead of assuming prior knowledge.
+### 1) Read the entire codebase
 
-## Quality Gate (must pass before finishing)
+- Read every source file in the repository to build a complete mental model.
+- Pay special attention to:
+  - Entry points (CLI commands, server startup, job runners)
+  - Public-facing interfaces (API routes, CLI commands, UI pages)
+  - Module boundaries and dependency directions
+  - Configuration files, environment variables, and external service integrations
+  - Test files that document expected behavior
+- Record concrete file paths as evidence for every claim that will appear in documentation.
 
-- Ensure every non-trivial statement is traceable to repository evidence.
-- Ensure usage and debug steps are reproducible from current code.
-- Ensure architecture description reflects actual module boundaries.
-- Ensure outdated statements are removed, not only appended.
-- Ensure document categories and headings are chosen because they fit the content, not because the template listed them.
-- Ensure a newcomer can identify the correct next step from the document without already knowing the codebase.
-- Ensure the chosen document types align with common open source practice so contributors can find information where they expect it.
+### 2) Read existing project documentation as reference
 
-## Output Style
+- Enumerate all existing documentation files (`README.md`, `docs/**`, `CONTRIBUTING.md`, etc.).
+- Extract factual claims that can be cross-referenced with the codebase.
+- Note gaps where documentation is missing or outdated.
+- Treat existing docs as secondary sources; code is always the primary source of truth.
 
-- Write concise but high-context documentation for humans, not placeholder-driven template output.
-- Use headings, short bullets, tables, and runnable command snippets when they improve scanning.
-- Prefer direct language and avoid speculative wording.
-- Make headings descriptive enough that a reader can skim the table of contents and know which page or section to open.
+### 3) Generate new documentation following the template structure
 
-## Reference Template
+- Create `docs/features/`, `docs/architecture/`, and `docs/principles/` directories if they do not exist.
+- For each category, classify findings from the codebase and write focused markdown files.
+- Titles must be descriptive and immediately tell the reader what the file covers.
+- Write in the user's language unless the repository clearly uses a different documentation language.
+
+**Features generation checklist:**
+- Identify all user-facing capabilities from routes, CLI commands, UI pages, and job outputs.
+- Group into functional categories (e.g., authentication, data export, notifications).
+- Write BDD scenarios for each feature using Given/When/Then.
+- Each file covers one functional category.
+
+**Architecture generation checklist:**
+- Identify major modules or layers from the codebase directory structure and import graph.
+- For each module, extract the design principles that govern its structure and boundaries.
+- Keep principles at the macro level; avoid principles that would need updating for minor code changes.
+- Each file covers one module or architectural layer.
 
-- `references/templates/category-based-project-docs-template.md`: category-based template and reusable section blocks for newcomer-friendly project documentation.
+**Principles generation checklist:**
+- Identify recurring patterns in code style, naming, error handling, dependency management, and testing.
+- Categorize patterns into separate files (e.g., `coding-style.md`, `naming-conventions.md`, `dependency-management.md`).
+- Support each principle with a brief rationale traceable to the codebase.
 
-## External Documentation Basis
+### 4) Remove old documentation that does not conform
+
+- Scan `docs/` and the repository root for documentation files that do not fit the new structure.
+- Remove any documentation file whose content has been fully migrated into the new structure.
+- Keep only files that belong to the new structure or have not yet been migrated.
+- When in doubt, preserve the file and note it as a candidate for later migration.
+
+### 5) Update AGENTS.md/CLAUDE.md via maintain-project-constraints
+
+- After the new documentation is complete, invoke `maintain-project-constraints` to refresh `AGENTS.md/CLAUDE.md`.
+- `maintain-project-constraints` will read the codebase (or the newly generated docs), extract macro business goals, write them to `AGENTS.md`/`CLAUDE.md`, and maintain the project document index.
+
+## Quality Gate (must pass before finishing)
+
+- Every feature description is written from a user perspective with no code references.
+- Every architecture principle is macro-level and resilient to minor code changes.
+- Every code principle is traceable to concrete examples in the codebase.
+- All generated files have descriptive, scannable titles.
+- No stale documentation remains that duplicates or contradicts the new structure.
+- `maintain-project-constraints` has been run and `AGENTS.md`/`CLAUDE.md` is up to date.
+
+## Reference Template
 
-- Diataxis: use the tutorial / how-to / reference / explanation model as the primary content classification.
-- The Good Docs Project: use common open source template types such as README, quickstart, tutorial, how-to, troubleshooting, glossary, and style-oriented guidance as practical packaging patterns.
-- GitHub open source guidance: treat `README`, `CONTRIBUTING`, license, code of conduct, and security policy as common repository-level documents when the project has contributor-facing community workflows.
+- `references/templates/standardized-docs-template.md`: describes the three-category documentation structure, writing rules, and quality checklist for each category.

package/align-project-documents/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Align Project Documents"
-  short_description: "Generate or sync project docs against the real codebase"
-  default_prompt: "Use $align-project-documents to inspect the repository first, ground every claim in code/config/test evidence, then generate or align project documentation covering usage, architecture, configuration, debugging, testing, and runtime notes without guessing."
+  short_description: "Generate standardized project docs under docs/features/, docs/architecture/, and docs/principles/ from code evidence"
+  default_prompt: "Use $align-project-documents to read the entire codebase first, ground every claim in code/config/test evidence, then generate standardized project documentation in three categories: features (BDD-described, user perspective), architecture (macro-level design principles by module), and principles (code style, naming conventions, development constraints). Remove old non-conforming docs and refresh AGENTS.md/CLAUDE.md via maintain-project-constraints."

package/align-project-documents/references/templates/standardized-docs-template.md

@@ -0,0 +1,119 @@
+# Standardized Project Documentation Template
+
+Use this template as the target structure when generating or aligning project documentation. Every document must be grounded in codebase evidence, not assumptions.
+
+## 1. Category Selection Rules
+
+| Category | Purpose | Writing rule | Output path |
+| --- | --- | --- | --- |
+| Features | What the system does for its users | BDD (Given/When/Then), user perspective, no code references | `docs/features/<category>.md` |
+| Architecture | How the system is designed at a macro level | Design principles, module responsibilities, boundary rules | `docs/architecture/<module>.md` |
+| Principles | How code is written and organized | Recurring patterns, naming conventions, development constraints | `docs/principles/<topic>.md` |
+
+## 2. Features Template (`docs/features/<category>.md`)
+
+Every feature file must:
+
+- Use a descriptive title that names the functional area.
+- Describe only user-visible behavior; never mention file paths, function names, or database tables.
+- Use BDD phrasing: **Given** (precondition) → **When** (action) → **Then** (outcome).
+- Group related features under subheadings within the file.
+
+```markdown
+# <功能類別名稱>
+
+## <功能名稱>
+
+- **Given** <前置條件>
+- **When** <使用者操作>
+- **Then** <預期結果>
+
+## <功能名稱>
+
+- **Given** <前置條件>
+- **When** <使用者操作>
+- **Then** <預期結果>
+```
+
+### Feature classification guide
+
+To identify feature categories from the codebase:
+
+1. List every user-facing entry point: CLI commands, API routes, UI pages, scheduled jobs, webhook handlers.
+2. Group entries by the user goal they serve, not by the module that implements them.
+3. Name each group with a term that a user (not a developer) would recognize.
+
+## 3. Architecture Template (`docs/architecture/<module>.md`)
+
+Every architecture file must:
+
+- Use a descriptive title that names the module or layer.
+- State design principles, not implementation details.
+- Keep each principle macro-level so it survives minor code changes.
+- Focus on: module boundaries, data flow direction, integration contracts, and responsibility allocation.
+
+```markdown
+# <模組／層名稱> 設計原則
+
+## <原則標題>
+
+<原則描述：這條原則規範什麼、為什麼這樣設計、適用範圍>
+
+## <原則標題>
+
+<原則描述>
+```
+
+### Architecture principle test
+
+Before writing a principle, ask: "Would a refactor that renames files or extracts a helper violate this principle?" If yes, the principle is too specific. Rewrite it at a higher level.
+
+## 4. Principles Template (`docs/principles/<topic>.md`)
+
+Every principles file must:
+
+- Use a descriptive title that names the convention area.
+- State the convention clearly.
+- Provide rationale traceable to the codebase.
+- Include a brief example from the codebase (not invented).
+
+```markdown
+# <慣例類別>
+
+## <慣例名稱>
+
+<慣例描述>
+
+**理由**: <為什麼採用此慣例>
+
+**範例**: <從代碼庫提取的具體範例>
+```
+
+### Principles classification guide
+
+Common principle categories to scan for:
+
+- **命名約定** (`naming-conventions.md`): file naming, variable naming, function naming, type naming
+- **程式碼風格** (`coding-style.md`): formatting, import ordering, export conventions, comment usage
+- **依賴管理** (`dependency-management.md`): how dependencies are declared, versioning strategy, internal dependency rules
+- **錯誤處理** (`error-handling.md`): error creation, propagation, and logging patterns
+- **測試慣例** (`testing-conventions.md`): test file placement, naming, mock/stub usage, coverage expectations
+
+## 5. Evidence Checklist
+
+Before finishing any document, confirm:
+
+- [ ] Every feature claim maps to a user-visible entry point found in the codebase.
+- [ ] Every architecture principle maps to a real module boundary or design decision visible in the code.
+- [ ] Every code principle is supported by at least one concrete example from the codebase.
+- [ ] No removed documentation content has been lost without being replaced in the new structure.
+- [ ] File titles are descriptive enough to be understood in the table of contents.
+
+## 6. Removal Rules for Old Documentation
+
+When old documentation exists:
+
+1. If its content has been fully migrated into the new `docs/features/`, `docs/architecture/`, or `docs/principles/` structure, remove it.
+2. If it contains content not yet covered by the new structure, migrate that content first, then remove it.
+3. If it serves a purpose outside the three categories (e.g., `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`), keep it unless it is stale.
+4. Never leave both old and new documentation covering the same topic in place.

package/archive-specs/README.md

@@ -1,13 +1,13 @@
 # archive-specs
 
-A documentation skill that converts completed spec files and batch-level coordination files into standardized project docs and archives the consumed planning files. It produces a concise `README.md` plus a categorized document set grounded in real repository evidence.
+A documentation skill that converts completed spec files and batch-level coordination files into the standardized project documentation structure and archives the consumed planning files. It delegates documentation generation to `align-project-documents` and constraint file refresh to `maintain-project-constraints`.
 
 ## Core capabilities
 
 - Scans `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and batch-level `coordination.md` collections as documentation input.
 - Reconciles spec claims against code, config, scripts, and deployment files.
-- Standardizes both new and existing project docs into topic-based files for setup, configuration, architecture, features, and developer onboarding.
-- Provides dedicated reference templates for the top-level README, the documentation index/reference list, and each category document.
+- Delegates to `align-project-documents` to generate standardized docs under `docs/features/` (BDD user-facing features), `docs/architecture/` (macro-level design principles), and `docs/principles/` (code conventions and constraints).
+- Delegates to `maintain-project-constraints` to refresh `AGENTS.md`/`CLAUDE.md` with business goals, common commands, and the project documentation index.
 - Archives superseded spec source files after a successful conversion, and deletes them only when the repository clearly does not need historical retention.
 - Preserves active batch coordination files until no remaining spec set still depends on their shared preparation or replacement direction.
 - Keeps unknown or unverifiable details explicit instead of guessing.
@@ -25,34 +25,21 @@ A documentation skill that converts completed spec files and batch-level coordin
     └── templates/
         ├── readme.md
         ├── docs-index.md
-        ├── getting-started.md
-        ├── configuration.md
-        ├── architecture.md
         ├── features.md
-        └── developer-guide.md
+        ├── architecture.md
+        └── principles.md
 ```
 
 ## Default outputs
 
-- `README.md`
-- `docs/README.md`
-- `docs/getting-started.md`
-- `docs/configuration.md`
-- `docs/architecture.md`
-- `docs/features.md`
-- `docs/developer-guide.md`
-
-## Required doc coverage
-
-- Installation and deployment
-- Configuration and environment variables
-- External services and API key acquisition/setup steps when applicable
-- Project architecture
-- Project feature introductions
-- Information developers should understand before changing the project
+- `docs/features/<category>.md` — BDD-described user-facing capabilities by functional category
+- `docs/architecture/<module>.md` — macro-level design principles by module
+- `docs/principles/<topic>.md` — code conventions and development constraints
+- `README.md` — concise project overview (kept short, links to docs/)
+- `AGENTS.md`/`CLAUDE.md` — business goals, common commands, and doc index (maintained by `maintain-project-constraints`)
 
 ## Notes
 
 - Prefer code, config, and deployment files over stale spec text when they disagree.
-- If the repository already has docs, rewrite them into the same categorized structure instead of leaving mixed documentation formats.
-- Keep `README.md` short and let `docs/README.md` act as the reference list for deeper topic docs.
+- If the repository already has docs, delegate to `align-project-documents` to rewrite them into the standardized structure.
+- Keep `README.md` short; the documentation index lives in `AGENTS.md`/`CLAUDE.md`.

package/archive-specs/SKILL.md

@@ -1,33 +1,33 @@
 ---
 name: archive-specs
-description: Convert completed project plan sets into maintainable project documentation and archive the consumed planning files. Use when users want to consolidate `spec.md`/`tasks.md`/`checklist.md`/`contract.md`/`design.md` and any batch-level `coordination.md` into evidence-backed docs covering installation and deployment, configuration, external service setup, architecture, feature introductions, and developer onboarding context.
+description: Convert completed project plan sets into maintainable project documentation and archive the consumed planning files. Use when users want to consolidate `spec.md`/`tasks.md`/`checklist.md`/`contract.md`/`design.md` and any batch-level `coordination.md` into the standardized docs/features/, docs/architecture/, docs/principles/ structure, then refresh AGENTS.md/CLAUDE.md via maintain-project-constraints.
 ---
 
 # Archive Specs
 
 ## Dependencies
 
-- Required: `align-project-documents` to align repository docs with current code before archiving, and `maintain-project-constraints` to synchronize `AGENTS.md/CLAUDE.md` after the doc update.
+- Required: `align-project-documents` to generate and align the standardized project documentation under `docs/features/`, `docs/architecture/`, and `docs/principles/`, and `maintain-project-constraints` to refresh `AGENTS.md`/`CLAUDE.md` with the updated business goals and documentation index after the doc update.
 - Conditional: none.
 
 ## Standards
 
 - Evidence: Treat code, config, deployment files, and current spec files as evidence sources; never guess when a detail is missing.
-- Execution: Inventory all relevant specs first, reconcile them with the current repository, use `align-project-documents` to update durable project docs, use `maintain-project-constraints` to refresh `AGENTS.md/CLAUDE.md` when repository guidance changed, then archive only the truly consumed planning artifacts.
-- Quality: Prefer source-of-truth behavior over stale plan text, align existing docs to the same standard structure, and call out unknowns explicitly instead of inventing missing setup details.
-- Output: Produce synchronized durable docs (`README.md`, categorized project docs, and `AGENTS.md/CLAUDE.md` when needed), then archive or remove superseded spec files after the conversion is complete.
+- Execution: Inventory all relevant specs first, reconcile them with the current repository, delegate documentation generation to `align-project-documents`, delegate `AGENTS.md`/`CLAUDE.md` refresh to `maintain-project-constraints`, then archive only the truly consumed planning artifacts.
+- Quality: Prefer source-of-truth behavior over stale plan text, align existing docs to the standardized three-category structure, and call out unknowns explicitly instead of inventing missing setup details.
+- Output: Produce synchronized standardized docs under `docs/features/`, `docs/architecture/`, and `docs/principles/`, a concise `README.md` when appropriate, and an up-to-date `AGENTS.md`/`CLAUDE.md`, then archive or remove superseded spec files after conversion is complete.
 
 ## Goal
 
-Convert completed planning artifacts into stable, standardized project documentation, then archive the consumed specs so active planning files stay separate from durable project docs.
+Convert completed planning artifacts into the standardized project documentation structure, refresh the project constraint files, then archive the consumed specs so active planning files stay separate from durable project docs.
 
 ## Workflow
 
 ### 1) Inventory documentation sources
 
 - Find all relevant planning files such as `docs/plans/**/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and any batch-level `coordination.md`.
-- Read existing `README*`, deployment scripts, manifests, env examples, infra files, CI configs, and representative source modules.
-- Build a source map for setup commands, environments, external services, module boundaries, and implemented features.
+- Read existing `README*`, `docs/**`, deployment scripts, manifests, env examples, infra files, CI configs, and representative source modules.
+- Build a source map for implemented features, module boundaries, external services, and configuration details.
 
 ### 2) Reconcile spec claims with the current repository
 
@@ -41,42 +41,22 @@ Convert completed planning artifacts into stable, standardized project documenta
 - Use `coordination.md` to understand shared preparation, ownership boundaries, legacy cutover direction, and which old features or paths were intentionally replaced across multiple spec sets.
 - Distinguish between completed scope that should become durable docs and still-active scope that remains planning material for follow-up work.
 
-### 3) Standardize existing project docs into categorized outputs
-
-- Hand the documentation rewrite/alignment work to `align-project-documents`; use the templates below only as the target shape and evidence checklist.
-- If the project already has `README.md`, handbooks, setup guides, architecture docs, or runbooks, rewrite or reorganize them so they follow this skill's standardized split-document structure instead of leaving mixed formats in place.
-- Use `references/templates/readme.md` for the concise project introduction.
-- Use `references/templates/docs-index.md` for the project documentation index and reference list.
-- Use the category templates to split content by topic so readers can open only what they need.
-- Default target outputs:
-  - `README.md`
-  - `docs/README.md`
-  - `docs/getting-started.md`
-  - `docs/configuration.md`
-  - `docs/architecture.md`
-  - `docs/features.md`
-  - `docs/developer-guide.md`
-- Ensure the categorized docs cover: installation and deployment, configuration, external services with required credentials and API key acquisition tutorials when applicable, architecture and module boundaries, feature introductions, and developer onboarding context.
-- If the repository already uses different doc paths, preserve the established locations only when the resulting documents still match the same categorized sections and remain easy to maintain.
-
-### 4) Write the configuration and external-service guidance carefully
-
-- List each env var, config file, or secret only when supported by repository evidence.
-- For every external service, document:
-  - why the service is needed
-  - which local config or env vars are required
-  - how to create or locate the credential
-  - where to place the credential locally or in deployment
-  - any safe-development notes such as sandbox/test-mode usage
-- If the repository does not show how to obtain a credential, say so explicitly and point to the service's official setup page rather than guessing steps.
+### 3) Delegate documentation generation to align-project-documents
+
+- Hand the full documentation rewrite/alignment work to `align-project-documents`.
+- `align-project-documents` will read the entire codebase, generate standardized documentation under `docs/features/` (BDD-described user-facing capabilities), `docs/architecture/` (macro-level design principles by module), and `docs/principles/` (code style, naming conventions, development constraints), and remove old non-conforming documentation.
+- Provide `align-project-documents` with the reconciled spec findings from step 2 as supplementary context.
+
+### 4) Refresh AGENTS.md/CLAUDE.md via maintain-project-constraints
+
+- After `align-project-documents` has completed the documentation update, invoke `maintain-project-constraints`.
+- `maintain-project-constraints` will read the updated `docs/` structure, extract macro business goals, inventory common development commands, build the project documentation index, and write or update `AGENTS.md`/`CLAUDE.md` with exactly three sections: Common Development Commands, Project Business Goals, and Project Documentation Index.
+- If both `AGENTS.md` and `CLAUDE.md` exist, `maintain-project-constraints` will keep their content consistent.
 
 ### 5) Keep README short and the doc set navigable
 
-- `README.md` should stay short: project intro, quick install/deploy, major features, and key doc links.
-- `docs/README.md` should act as the reference list for the categorized docs.
-- Each category doc should stay focused on one topic instead of acting like another monolithic handbook.
-- Remove template placeholders and stale planning language before finishing.
-- After the docs are aligned, run `maintain-project-constraints` whenever the documentation changes imply `AGENTS.md/CLAUDE.md` needs to reflect updated workflows, commands, or repository capabilities.
+- If `README.md` does not exist or is outdated, create or update it as a short project overview with a link to the documentation index in `AGENTS.md`/`CLAUDE.md`.
+- Do not duplicate content that belongs in `docs/`.
 
 ### 6) Archive superseded spec files after successful conversion
 
@@ -91,7 +71,6 @@ Convert completed planning artifacts into stable, standardized project documenta
 ## Working Rules
 
 - Prefer the user's language unless the repository clearly uses another documentation language.
-- Keep examples executable and commands copyable.
 - Do not copy speculative roadmap items from specs into the main docs as if they already exist.
 - When a section cannot be completed from evidence, keep an explicit `Unknown` or `TBD (missing repository evidence)` marker.
 - The final repository state should not keep both standardized docs and redundant active spec files for the same completed scope.
@@ -102,8 +81,6 @@ Convert completed planning artifacts into stable, standardized project documenta
 
 - `references/templates/readme.md`: concise project overview template.
 - `references/templates/docs-index.md`: categorized project-doc index and reference list template.
-- `references/templates/getting-started.md`: installation and deployment template.
-- `references/templates/configuration.md`: configuration and external-service template.
-- `references/templates/architecture.md`: architecture template.
-- `references/templates/features.md`: feature guide template.
-- `references/templates/developer-guide.md`: development onboarding template.
+- `references/templates/features.md`: template for `docs/features/` BDD-described feature documentation.
+- `references/templates/architecture.md`: template for `docs/architecture/` macro-level design principles.
+- `references/templates/principles.md`: template for `docs/principles/` code conventions and development constraints.