diff --git a/docs/specification.md b/docs/specification.md index f0803345d..73526d8e3 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -47066,6 +47066,54 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a --- +### v3.9.0 — Documentation & Feature Updates + +**Goal**: Deliver comprehensive documentation improvements, targeted feature additions, quality enhancements, and developer-experience upgrades that do not fit within the scope of the major feature milestones (v3.2.0–v3.8.0). This milestone ensures the platform is well-documented, thoroughly tested, and ergonomic for both end-users and contributors before the next major capability cycle. + +**Spec Coverage**: §Documentation, §Quality Gates, §Cross-Cutting Concerns, §CLI Commands, §Module Definitions + +**Key ADRs**: No new ADRs required for this milestone. All changes are clarifications, documentation additions, or minor feature improvements that fall within existing architectural decisions. + +#### Deliverables + +| # | Deliverable | Spec Reference | Verifiable Check | +|---|-------------|----------------|-----------------| +| 1 | Comprehensive API reference documentation for all public modules | §Documentation — API Reference | `nox -s docs` passes; all public symbols have docstrings; MkDocs API reference renders without errors | +| 2 | User guide: Getting Started walkthrough (install → first plan) | §Documentation — User Guides | `docs/user-guide/getting-started.md` exists and covers install, init, resource add, action create, plan use/execute/apply | +| 3 | User guide: Actions and Plans deep-dive | §Documentation — User Guides | `docs/user-guide/actions-and-plans.md` exists; covers Action YAML schema, plan lifecycle, corrections, subplans | +| 4 | User guide: Resources and Projects | §Documentation — User Guides | `docs/user-guide/resources-and-projects.md` exists; covers resource types, DAG, project linking, context policies | +| 5 | Architecture documentation updated to reflect v3.6.0–v3.7.0 additions (LSP, devcontainer, TUI) | §Module Definitions | `docs/architecture.md` updated; LSP Registry, Devcontainer, TUI Materializer sections present | +| 6 | CONTRIBUTING.md updated with current nox session list, commit conventions, and PR workflow | §Cross-Cutting Concerns — Developer Experience | `CONTRIBUTING.md` reflects current `nox -l` output; commit message format documented | +| 7 | Improved error messages: all `ValueError`/`RuntimeError` raises include actionable guidance | §Cross-Cutting Concerns — Error Handling | Manual review of all `raise` statements; each includes a hint or remediation step | +| 8 | CLI `--help` text reviewed and updated for all commands | §CLI Commands | `agents --help` and all subcommand `--help` outputs are accurate and complete | +| 9 | Test coverage ≥ 97% maintained; new coverage for previously untested edge cases | §Quality Gates | `nox -s coverage_report` passes with ≥ 97% line coverage | +| 10 | Performance: no ASV benchmark regressions introduced by documentation or minor feature changes | §Quality Gates | `nox -s benchmarks` passes; no regression > 10% vs. v3.7.0 baseline | +| 11 | Technical debt: resolve all `TODO`/`FIXME` comments tagged for v3.9.0 | §Cross-Cutting Concerns — Technical Debt | `rg "TODO.*v3\.9|FIXME.*v3\.9"` returns no results | +| 12 | Developer tooling: `nox -s dev_setup` script for one-command contributor onboarding | §Cross-Cutting Concerns — Developer Experience | Running `nox -s dev_setup` on a clean checkout installs all dependencies and runs `nox -s lint typecheck unit_tests` successfully | +| 13 | Showcase examples: at least 3 end-to-end workflow examples in `examples/` | §Workflow Examples | `examples/` contains ≥ 3 subdirectories each with a `README.md`, action YAML, and actor YAML | +| 14 | FAQ document covering top 10 common user questions | §Documentation — FAQ | `docs/faq.md` contains ≥ 10 Q&A entries covering install, configuration, plan lifecycle, and troubleshooting | +| 15 | Changelog updated with all changes from v3.2.0 through v3.9.0 | §Documentation — Changelog | `CHANGELOG.md` has entries for each milestone; follows Keep a Changelog format | + +#### Key Architectural Constraints + +- **No breaking changes**: v3.9.0 must not introduce breaking changes to the public API, CLI interface, or A2A protocol extensions. All changes are additive or corrective. +- **Spec-first**: Any minor feature addition discovered during documentation work must be spec-covered before implementation proceeds, per the spec-first invariant. +- **Documentation co-located with code**: API reference documentation is generated from docstrings; user guides live in `docs/`; no documentation is duplicated across locations. +- **Error message format**: All user-facing error messages follow the pattern `. . .` — three sentences, actionable. +- **Nox session parity**: All quality gates remain executable via `nox`; no ad-hoc scripts introduced outside the `noxfile.py`. +- **Coverage floor**: The 97% line coverage floor established in v3.2.0 must not regress. New code must be covered before merge. + +#### Definition of Done + +- All 15 deliverables verified (documentation reviewed by at least one human reviewer; automated checks pass) +- `nox` passes with coverage ≥ 97% +- No open P0/P1 bugs in v3.9.0 milestone +- All 21 open milestone issues resolved or explicitly deferred to a future milestone with documented rationale +- Documentation site builds and deploys without errors (`nox -s docs`) +- CONTRIBUTING.md accurately reflects the current development workflow + +--- + ### Cross-Milestone Quality Gates These quality gates apply to **every milestone** and must pass before a milestone is considered complete: