Project living docs

Project Living Docs

Use NOC Living Docs as an agent memory router. For feature-archive projects, let the CLI identify or create the feature archive, read only routed docs, update overview.md through structured patches, record real evidence, and verify consistency. For simplified and v1 projects, keep the compatible legacy flow and do not silently migrate.

Trigger

Use this skill for:

• initializing or migrating noc_docs/
• discussing a requirement and then changing code
• new features, bug fixes, refactors, API/data/security/deployment changes
• checking whether code changes need docs updates
• querying or auditing project living docs

Do not use it for general questions that do not involve project memory, code behavior, requirements, guardrails, tests, or NOC documentation.

Execution

1. Detect the NOC layout from the machine-readable noc work <project> --path <code/path> --json --intent "<agreed requirement>" output and, if needed, noc_docs/.living-docs/config.json.
2. For layout: feature-archive, follow the feature-archive workflow below.
3. For layout: simplified, use the project-level three-file flow. Do not create features/, do not call feature ensure, and do not silently migrate.
4. For v1 small or domain, use the legacy feature/domain workflow. Do not convert the project to feature-archive unless the user explicitly asks for migration.

Feature-Archive Workflow

1. Run:

noc work /path/to/project --path <code/path> --json --intent "<agreed requirement>"

Use --staged or --changed when the Git diff is the clearest input. Use --feature <feature> when the user has named a specific feature.

2. Select the feature:
   • If candidates[0].confidence is high confidence and not ambiguous, use that existing feature.
   • If the user clearly requested a new business feature, create it with noc feature ensure <project> --id <ascii-kebab-id> --name "<display name>" --json. Use a stable English ASCII feature id; keep Chinese display names in name.
   • If candidates are ambiguous or low confidence, ask the user once which feature to use or whether to create a new one. Do not ask multiple NOC-internal questions.
3. Before editing code, read only the routed project memory and selected feature docs: project.md, guardrails.md, verification.md, and the relevant noc_docs/features/<feature-id>/overview.md.
4. Make the code change.
5. Run real, relevant verification commands from verification.md, the feature overview, or the project’s existing test conventions. Do not record passed unless the command actually ran and exited 0; passed requires exit_code 0.
6. Collect code evidence with noc evidence <project> --staged --json.
7. Record verification evidence with noc evidence record <project> --feature-id <feature-id> --file <evidence.json> --json.
8. Generate a structured patch from the explicit user requirement, actual code diff, and verification result. Apply it only with noc feature update <project> --id <feature-id> --patch-file <patch.json> --json.
9. Check consistency with noc check <project> --feature-impact-file <impact.json> --json.
10. Reply briefly in the user’s language, normally Chinese for language: zh-CN, naming the change, verification, and NOC docs updated.

Do not freely rewrite overview.md. Do not directly edit the whole overview, translate existing Chinese prose into English, invent requirements, turn plans into current implementation, mark tests passed without evidence, or classify ordinary changes as major changes.

Memory Impact

• none: formatting, comment fixes, local renames, behavior-preserving small refactors, implementation bug fixes that restore existing requirements, running existing tests, and ordinary tests added under the existing verification approach. Do not modify noc_docs/.
• project: project goals, project phase, major capabilities, technical boundaries, or architecture facts changed. In v2, update only project.md.
• guardrails: durable security, permission, data-loss, compatibility, public API, migration, or deployment constraints changed. In v2, update only guardrails.md.
• verification: standard test commands, build/release/acceptance procedures, or durable verification gates changed. In v2, update only verification.md.

Multiple durable impacts may apply; update only their corresponding files. Do not create change-record.md, test-record.md, notes.md, areas, or any new long-term document type for v2. For v1, keep reading the existing structure but apply the same semantic threshold and avoid routine document churn.

If the next Codex session did not know this fact, and that would not materially affect future work, do not store it in project memory.

For detailed workflow rules, read references/workflow.md.

Language Rules

When language: zh-CN, write feature names, confirmed requirements, current implementation notes, verification summaries, major changes, and final responses in Simplified Chinese. Preserve the user’s Chinese requirement wording when it is explicit. JSON/YAML keys, feature ids, CLI flags, paths, code identifiers, and commands stay English or in their original spelling. Do not translate existing Chinese documents to English.

Do Not Proceed

Stop and ask the user before editing code when:

• the request conflicts with guardrails.md or domain guardrails
• product intent conflicts with requirements.md and the intended direction is unclear
• affected feature/domain cannot be identified and the change is not obviously global
• required docs are missing and the task depends on unknown requirements or constraints
• the user asks to silently rewrite requirements to match current code
• the change touches security, permissions, billing, data loss, migrations, or public API contracts and the requested behavior is ambiguous
• the feature-archive candidate is ambiguous after noc work; ask the user once instead of guessing
• the project is simplified, small, or domain and the next step would require migration; migration requires an explicit user request

Definition Of Done

A task using this skill is done only when the rules for the detected protocol are satisfied.

v2 feature-archive projects

• noc work --json was used to identify candidate features
• high confidence candidates were selected automatically, or ambiguity was resolved by asking the user once
• new clear business features were created through noc feature ensure
• project.md, guardrails.md, verification.md, and the selected overview.md were read before code changes
• real verification was run, or a skipped verification reason was reported
• code and verification evidence were collected or recorded with noc evidence and noc evidence record
• overview.md was updated only through noc feature update with a structured patch
• noc check <project> --feature-impact-file <impact.json> --json passed, or failures were reported honestly

v2 simplified projects

• affected memory was identified through v2 routing data
• project.md, guardrails.md, and verification.md were read as routed, or missing files were called out
• the actual diff was classified by memory impact
• only the memory files selected by that impact were updated; none caused no memory update
• code changes and project memory agree
• available checks were run, or skipped with a reason
• no feature archive was created and no migration was performed unless the user explicitly requested it

v1 legacy projects

• the affected feature or domain was identified through the feature map
• required feature/domain docs were read, or missing docs were called out
• code changes and docs changes agree
• requirements.md changed only for intended behavior changes
• status.md reflects current behavior after behavior changes
• test-record.md records verification or explains why verification was not run
• change-record.md records important implementation changes, not routine churn
• indexes/checks were run when available, or skipped with a reason

Use a normal final response focused on development and test results. Do not output a fixed NOC template. Only when memory changed, append one short sentence such as Project memory updated: project.md.

References

• references/workflow.md: mode selection, fallback rules, conflict handling, work loop
• references/feature-doc-template.md: what each feature doc should contain
• references/domain-mode-guide.md: when and how to use domain mode
• references/codex-prompts.md: recommended user prompts for Codex plan/goal/code workflows