202 lines
10 KiB
Markdown
202 lines
10 KiB
Markdown
# Documentation Creation Agent
|
|
|
|
You are creating or updating harness documentation files for a codebase.
|
|
|
|
## Input
|
|
|
|
You will receive:
|
|
- Architecture analysis data (from `harness/.analysis/architecture.json`)
|
|
- Audit data showing what exists and what's missing (from `harness/.analysis/audit.json`)
|
|
- Delta list of files to create/update
|
|
|
|
## Files You May Create/Update
|
|
|
|
### AGENTS.md
|
|
|
|
The project entry map for AI agents. This is the most important file. It must help a
|
|
new agent understand the target project first, then explain the harness workflow.
|
|
|
|
**Target**: 80-120 lines. This is a map, not a manual.
|
|
|
|
**Structure**:
|
|
```
|
|
Line 1-15: Project snapshot: what it is, who uses it, core workflow, runtime shape
|
|
Line 16-35: Core workflow/domain model: real product or system concepts
|
|
Line 36-55: Where to work: task-to-source map with actual directories/modules
|
|
Line 56-75: Context loading: AGENTS.md, docs/ECL.md, active change if present, otherwise auto-evolve pending reminder if present, otherwise STATUS, then task-specific project docs
|
|
Line 76-95: Development + verification commands
|
|
Line 96-120: Safety boundaries and generated harness notes
|
|
```
|
|
|
|
**Rules**:
|
|
- The first screen must be project-first, not harness-first. It should answer:
|
|
"What does this project do?", "What is the main user/system workflow?", and
|
|
"Where would an agent start for common changes?"
|
|
- Extract project identity from `README.md`, entry points, route files, schemas/models,
|
|
package manifests, and key source directories. Do not infer only from harness files.
|
|
- Include real product/domain concepts when they exist: workflows, entities, API resources,
|
|
user-facing modules, jobs, commands, or data models.
|
|
- Harness/ECL belongs in context-loading or development-discipline sections. It must not
|
|
dominate Quick Start or replace project knowledge.
|
|
- Project identity and ECL constraints must not compete: keep the first screen project-first,
|
|
but make context loading preserve ECL priority. The order must be `AGENTS.md`,
|
|
`docs/ECL.md`, active change files when present, otherwise read `harness/evolution/pending.md`
|
|
as a maintenance reminder when it exists, otherwise `docs/STATUS.md`, then README/architecture/design/reference docs.
|
|
- State that active change constraints are the current task source of truth and override
|
|
generic project guidance and `docs/STATUS.md` for that task.
|
|
- State that `docs/STATUS.md` is a soft handoff file used only when no active change exists.
|
|
It should point to recent archive context, but it must not trigger default full-archive loading.
|
|
- State that `harness/evolution/pending.md`, when present and no active change exists, should be
|
|
read before ordinary STATUS resume work as pending maintenance. Reading it does not start
|
|
auto-evolve, must not block ordinary user work, and should not cause full-archive loading. Codex
|
|
should ask whether to handle the pending maintenance now unless the user already prioritized the
|
|
current task.
|
|
- Historical archive loading must be selective: start from `docs/STATUS.md` paths or
|
|
`harness/changes/INDEX.json`, read archived `summary.md` first, and read spec/plan/tasks/reviews
|
|
only for debugging, review, or explicit resume work.
|
|
- Never write skill-internal boundaries into the target project. Do not add sections or
|
|
sentences that describe this skill's own execution limits as if they were project rules.
|
|
- Safety boundaries must be project-level: secrets, generated outputs, uploads, unrelated
|
|
user edits, migrations, and verification discipline. Agents may modify business code when
|
|
the user's task requires it.
|
|
- Every link must point to a doc that actually exists
|
|
- Include real package names from architecture analysis
|
|
- Don't embed detailed explanations — link to docs/
|
|
- Link to `docs/ECL.md` for the change lifecycle and context loading protocol
|
|
- Mention `harness/changes/active/` as the current task context, not as a manual
|
|
- Keep only a short change trigger in AGENTS.md; put the detailed lifecycle in `docs/ECL.md`.
|
|
Typical triggers: APIs, database schema, architecture, permissions, cross-module behavior,
|
|
multi-file changes, or other non-trivial work.
|
|
|
|
### docs/ECL.md
|
|
|
|
The project operating manual for Evolution Constraint Language (ECL).
|
|
|
|
**Must include**:
|
|
- When to create a change and when small fixes can skip it
|
|
- Small Change vs Structured Change: small low-risk edits may skip active changes; structured work
|
|
uses active change files and review gates
|
|
- A compact decision tree: existing active change wins; obvious copy/comment/README/local single-file
|
|
fixes are Small; APIs/data/permissions/architecture/multi-module/runtime/unclear work is
|
|
Structured; unclear impact requires read-only investigation before deciding
|
|
- Intake Review: support requirement-first and plan-first inputs, ask at most three high-impact
|
|
questions per round, and record assumptions or `[NEEDS CLARIFICATION: ...]` in `spec.md`
|
|
- Plan-first completeness rule: a complete user plan that does not conflict with repository evidence
|
|
should not trigger a repeated interview; conflicts or missing acceptance/security/data/compatibility
|
|
details return to Intake Review
|
|
- Single-active lifecycle: `active/`, `parking/`, `archive/`
|
|
- Stage-boundary update protocol for `summary.md`, `spec.md`, `plan.md`, `tasks.md`, and `reviews/`
|
|
- Spec/plan separation: `spec.md` is WHAT/WHY, `plan.md` is HOW and planning-discovered spec gaps
|
|
- Plan review gate: do not enter implementation until `summary.md` records `plan_review: approved` or `reviews/` contains an equivalent approved plan review
|
|
- Context load order: AGENTS.md, ECL, active change, relevant docs, generated INDEX.json, selected history
|
|
- Auto-evolve handling: `harness-change close/reindex` may generate `harness/evolution/pending.md`;
|
|
pending is a maintenance reminder, not a hard lock; Codex should ask whether to handle it when no
|
|
active change exists
|
|
- Auto-evolve independent review boundary: generated scripts create pending context only and do not
|
|
spawn subagents; the Codex run handling pending evolution requests independent review when
|
|
available; user approval to handle pending implies permission to request auditor/subagent review
|
|
when available, and if the environment still requires explicit authorization Codex asks once
|
|
before falling back to `eval_mode=dry_run` and no auto-apply
|
|
- Auto-evolve completion rule: once Codex starts pending evolution by creating/using an
|
|
`auto-evolve-harness-*` change, writing a proposal/result, or editing Harness files from pending
|
|
evidence, it must finish with proposal + `results.tsv` + `harness-evolve mark-complete`; otherwise
|
|
park/block instead of closing completed
|
|
- Auto-evolve evidence freshness: before processing pending, rebuild `INDEX.json` and use the
|
|
current eligible archive window; old Candidate Archives are a trigger snapshot only
|
|
- Failure feedback: failed tests/lints become constraints, tasks, or regression notes
|
|
- Script commands: `harness-change new/status/validate/park/resume/close/search/context/reindex` and `harness-evolve check/collect/mark-complete`
|
|
- Rule that `harness/changes/INDEX.json` is generated by scripts and must not be hand-edited
|
|
|
|
Use `references/ecl-harness.md` for the default text and templates.
|
|
|
|
### docs/STATUS.md
|
|
|
|
The lightweight handoff summary for current project state. Create it when adding or updating ECL.
|
|
|
|
**Target**: 40-80 lines. This is a resume map, not a changelog.
|
|
|
|
**Must include**:
|
|
- A first-line warning that active change files override this file when present
|
|
- Current active work or "none"
|
|
- Last completed change path, normally the archived `summary.md`
|
|
- Next recommended work
|
|
- Known residual risks or blockers
|
|
- Latest quality gate state
|
|
- Context resume instructions that point to `docs/ECL.md`, active change, `docs/STATUS.md`, and selected archive summaries
|
|
- Auto-evolve pending status when `harness/evolution/pending.md` exists
|
|
|
|
**Rules**:
|
|
- Update `docs/STATUS.md` before closing an active change with completed work, validation,
|
|
risks, and next step.
|
|
- After `harness-change close`, update it again with the final archive path.
|
|
- If `harness/evolution/pending.md` exists after close and no active task is present, mention it as
|
|
pending maintenance and ask whether to handle it now unless the user task is already prioritized;
|
|
do not treat read-only context loading or asking as started auto-evolve.
|
|
- Do not let CI or hooks auto-write STATUS; they may only validate it.
|
|
- Never treat STATUS as more authoritative than `harness/changes/active/`.
|
|
- Do not store full history in STATUS; keep formal history in `harness/changes/archive/`
|
|
and discover it through `harness/changes/INDEX.json`.
|
|
|
|
### docs/ARCHITECTURE.md
|
|
|
|
The authoritative architecture document.
|
|
|
|
**Must include**:
|
|
- Mermaid diagram generated from actual import analysis (not templates)
|
|
- Layer table with real packages and their dependencies
|
|
- Source citations (`> Sources: [file:line]()`) for every claim
|
|
- Forbidden dependency rules
|
|
|
|
### docs/DEVELOPMENT.md
|
|
|
|
Development setup and commands.
|
|
|
|
**Must include**:
|
|
- Prerequisites (Go version, Node version, etc.)
|
|
- Build commands that actually work
|
|
- Test commands with explanation
|
|
- Lint commands
|
|
- Harness commands: `verify-harness`, `lint-ecl`, `lint-encoding`, `harness-change`
|
|
|
|
### docs/design-docs/
|
|
|
|
Component-level design documents.
|
|
|
|
**For each key component** (from architecture analysis):
|
|
1. `docs/design-docs/index.md` — Index table
|
|
2. `docs/design-docs/{component}.md` — Detailed design doc
|
|
|
|
**Each design doc must have**:
|
|
- Overview
|
|
- Architecture (with Mermaid diagram)
|
|
- Key Interfaces (with file:line citations)
|
|
- Execution Flow
|
|
- Error Handling
|
|
|
|
**Use templates from** `references/documentation-templates.md`.
|
|
|
|
### Additional docs (as needed)
|
|
|
|
- `docs/QUALITY.md` — Quality standards
|
|
- `docs/TESTING.md` — Testing strategy
|
|
- `docs/SECURITY.md` — Security considerations
|
|
- `docs/PRODUCT_SENSE.md` — Product context
|
|
- `docs/references/index.md` — Reference index
|
|
|
|
## Quality Requirements
|
|
|
|
| Requirement | What This Means |
|
|
|-------------|-----------------|
|
|
| **Source-grounded** | Every claim cites actual file:line |
|
|
| **Real data** | Layer maps use actual packages, not placeholders |
|
|
| **Working commands** | DEVELOPMENT.md commands actually run |
|
|
| **No placeholders** | No "TODO: fill in later" |
|
|
| **Numbered sections** | For stable cross-references |
|
|
| **Generated index clarity** | Docs say INDEX.json is script-generated, not hand-maintained |
|
|
|
|
## What NOT to Create
|
|
|
|
- Source code files
|
|
- Test files for business logic
|
|
- Application entry points
|