🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
pi-agent-codebase-workflows
Advanced tools
pi-agent-codebase-workflows - npm Package Compare versions
+83
| # Changelog | ||
| All notable changes to this project are documented here. | ||
| ## [Unreleased] | ||
| ### Added | ||
| - None. | ||
| ### Fixes | ||
| - None. | ||
| ## [0.3.1] - 2026-05-18 | ||
| ### Added | ||
| - Added shared artifact compatibility contracts across `safe-start`, `codebase-recon`, `safe-change`, and `arch-code-review`. | ||
| - Added safe-start-compatible artifact handling for `REPO_INVENTORY.md`, `PROJECT_INTENT.md`, `DATA_FLOW.md`, `DESIGN_ISSUES.md`, `TESTING_STRATEGY.md`, `VALIDATION_BASELINE.md`, and `SCOPES.md`. | ||
| - Added scoped safe-start guidance for monorepos, enterprise-grade systems, dev-tools platforms, infra/IaC repos, and multi-service systems. | ||
| - Added planned/observed/currentness header guidance for durable agent docs. | ||
| - Added `CHANGELOG.md` and included it in the package files. | ||
| ### Fixes | ||
| - Fixed workflow drift between safe-start outputs, codebase-recon artifacts, safe-change preflight, and architecture review expectations. | ||
| - Fixed scoped-doc read ordering so workflows select matching scoped docs before falling back to repo-level inventory and validation baseline docs. | ||
| ## [0.3.0] - 2026-05-17 | ||
| ### Added | ||
| - Added `safe-start` greenfield project workflow with eight passes from intent capture through handoff to safe-change. | ||
| - Added safe-start prompt templates for intent, data flow, architecture, contract docs, scaffold planning, validation baseline, vertical slice, handoff, and all-in-one mode. | ||
| - Added README and tutorial coverage for greenfield starts. | ||
| - Added package metadata for the `safe-start` skill and prompts. | ||
| ### Fixes | ||
| - None. | ||
| ## [0.2.0] - 2026-05-15 | ||
| ### Added | ||
| - Added hierarchical scoped reconstruction docs for path and domain scopes. | ||
| - Added `docs/agent/SCOPES.md` guidance for scope discovery, ownership, status, and external contracts. | ||
| - Added scoped-doc support to reconstruction, safe-change, and architecture-review workflows. | ||
| - Added modular safe-change reference docs for bug fixes, features, refactoring, risk fixes, preflight, docs updates, and scoped docs. | ||
| - Added workflow tutorial and troubleshooting documentation. | ||
| ### Fixes | ||
| - Made scoped `README.md` files optional instead of required for each scope. | ||
| - Clarified scoped-doc fallback behavior and review/preflight wording. | ||
| ## [0.1.1] - 2026-05-14 | ||
| ### Added | ||
| - None. | ||
| ### Fixes | ||
| - Clarified consolidation disagreement handling so recon preserves disagreement evidence instead of silently deleting contradictions. | ||
| ## [0.1.0] - 2026-05-14 | ||
| ### Added | ||
| - Added initial pi package for codebase workflow skills and prompt templates. | ||
| - Added `codebase-recon` workflow for bounded reconstruction passes, consolidation, ADRs, and risk-to-test planning. | ||
| - Added `safe-change` workflow for documented-codebase changes across bug fixes, features, refactors, risk fixes, test-only work, and docs-only work. | ||
| - Added `arch-code-review` workflow for architecture-aware review of diffs. | ||
| - Added prompt templates for reconstruction, safe-change implementation/design flows, risk fixes, and architecture review. | ||
| - Added README, package metadata, MIT license, and pi package configuration. | ||
| - Added focus/scope argument documentation across workflows and prompts. | ||
| - Added project credits. | ||
| ### Fixes | ||
| - Fixed Mario Zechner credit links. |
+2
-1
| { | ||
| "name": "pi-agent-codebase-workflows", | ||
| "version": "0.3.0", | ||
| "version": "0.3.1", | ||
| "description": "Pi skills and prompt templates for safe greenfield starts, codebase reconstruction, architecture-aware review, and safe changes.", | ||
@@ -32,2 +32,3 @@ "license": "MIT", | ||
| "README.md", | ||
| "CHANGELOG.md", | ||
| "LICENSE" | ||
@@ -34,0 +35,0 @@ ], |
@@ -14,2 +14,35 @@ --- | ||
| ## Artifact Compatibility Contract | ||
| Architecture review accepts artifacts produced by both `safe-start` and `codebase-recon`. | ||
| Canonical repo-level docs may include: | ||
| ```text | ||
| docs/agent/ | ||
| REPO_INVENTORY.md | ||
| PROJECT_INTENT.md | ||
| ARCHITECTURE.md | ||
| DATA_FLOW.md | ||
| DATA_MODEL.md | ||
| INVARIANTS.md | ||
| DEPENDENCY_RULES.md | ||
| DESIGN_ISSUES.md | ||
| RISK_REGISTER.md | ||
| CHANGE_GUIDE.md | ||
| TESTING_STRATEGY.md | ||
| VALIDATION_BASELINE.md | ||
| SCOPES.md | ||
| ``` | ||
| Respect artifact headers when present: | ||
| ```text | ||
| Status: current | partial | stale | ||
| Evidence: planned | observed | mixed | ||
| Last validated: unknown | <date> | ||
| ``` | ||
| Treat `planned` docs as design intent, not source evidence. Use source diff and observed docs as implementation truth. Report divergence from intent only when it is unacknowledged, risky, or violates current docs/contracts. | ||
| ## Scoped Docs Discovery | ||
@@ -28,4 +61,6 @@ | ||
| - read top-level docs as fallback for missing categories and repo-wide rules | ||
| - safe-start scoped docs may include `PROJECT_INTENT.md`, `DATA_FLOW.md`, `TESTING_STRATEGY.md`, and `VALIDATION_BASELINE.md`; read them only when relevant to changed files/behavior | ||
| - for cross-scope diffs, read relevant scoped `CONTRACTS.md` and `DEPENDENCY_RULES.md` from each touched owner/consumer scope | ||
| - verify matched source paths still exist before treating scoped docs as current | ||
| - when scoped docs are marked `planned`, use them as intent and verify implementation-sensitive claims against source evidence | ||
@@ -38,5 +73,10 @@ ## Rules | ||
| - Read only relevant deeper docs: | ||
| - `docs/agent/CHANGE_GUIDE.md` when present | ||
| - `docs/agent/SCOPES.md` when present | ||
| - matched scoped `README.md` if present, and relevant scoped docs when present | ||
| - matching scoped `REPO_INVENTORY.md` or top-level `docs/agent/REPO_INVENTORY.md` when entry points, commands, or external boundaries matter | ||
| - matching scoped `VALIDATION_BASELINE.md` or top-level `docs/agent/VALIDATION_BASELINE.md` when build/test/tooling/validation behavior changes | ||
| - `docs/agent/PROJECT_INTENT.md` for scope, non-goals, users, journeys, or product-sensitive changes | ||
| - `docs/agent/ARCHITECTURE.md` | ||
| - `docs/agent/DATA_FLOW.md` for user journeys, pipelines, transformations, side effects, and error states | ||
| - `docs/agent/DATA_MODEL.md` | ||
@@ -46,3 +86,4 @@ - `docs/agent/INVARIANTS.md` | ||
| - `docs/agent/RISK_REGISTER.md` | ||
| - `docs/agent/CHANGE_GUIDE.md` | ||
| - `docs/agent/DESIGN_ISSUES.md` for known drift, deferred decisions, or refactor risks | ||
| - `docs/agent/TESTING_STRATEGY.md` for test coverage expectations and validation shape | ||
| - scoped `CONTRACTS.md` files for touched cross-scope APIs, shared types, schemas, events, generated clients, or persistence boundaries | ||
@@ -58,10 +99,15 @@ - Prioritize correctness, architecture drift, data consistency, side-effect boundaries, public contracts, and tests. | ||
| - Does diff match documented architecture and dependency directions? | ||
| - Does diff preserve project intent/non-goals, or intentionally update them? | ||
| - Are invariants preserved or intentionally updated? | ||
| - Are data model/schema changes documented and tested? | ||
| - Are data-flow, transformation, side-effect, or error-state changes documented and tested? | ||
| - Are side effects kept at existing boundaries? | ||
| - Are public contracts/backward compatibility respected? | ||
| - Are known risk areas touched? | ||
| - Are tests sufficient for changed behavior? | ||
| - Are known risk areas or `DESIGN_ISSUES.md` items touched or worsened? | ||
| - Are tests sufficient for changed behavior and aligned with `TESTING_STRATEGY.md` when present? | ||
| - Are validation baseline commands still correct after build/test/tooling changes? | ||
| - If scoped docs exist, did diff update owner/consumer docs and `SCOPES.md` where ownership/contracts changed? | ||
| - Did implementation combine feature, bug fix, and refactoring accidentally? | ||
| - Are docs updated only for durable semantic changes? | ||
| - Are docs marked `planned` now backed by observed implementation, still valid as intent, or stale? | ||
@@ -68,0 +114,0 @@ ## Output |
@@ -24,5 +24,42 @@ --- | ||
| ## Artifact Compatibility Contract | ||
| Codebase-recon artifacts must remain compatible with projects bootstrapped by `safe-start` and later changed by `safe-change`. | ||
| Canonical repo-level artifacts: | ||
| ```text | ||
| AGENTS.md | ||
| docs/ | ||
| agent/ | ||
| REPO_INVENTORY.md | ||
| PROJECT_INTENT.md # preserve/update when present; create only when useful | ||
| ARCHITECTURE.md | ||
| DATA_FLOW.md # preserve/update when present; create only when useful | ||
| DATA_MODEL.md | ||
| INVARIANTS.md | ||
| DEPENDENCY_RULES.md | ||
| DESIGN_ISSUES.md | ||
| RISK_REGISTER.md | ||
| CHANGE_GUIDE.md | ||
| TESTING_STRATEGY.md # preserve/update when present; create only when useful | ||
| VALIDATION_BASELINE.md # preserve/update when present; create only when useful | ||
| adr/ | ||
| 0001-observed-architecture.md | ||
| ``` | ||
| Artifact header guidance when creating or updating durable docs: | ||
| ```text | ||
| Status: current | partial | stale | ||
| Evidence: planned | observed | mixed | ||
| Last validated: unknown | <date> | ||
| ``` | ||
| Treat `safe-start` `planned` docs as intent until source evidence confirms them. Recon output should prefer `observed` evidence and should not silently delete intent docs; mark drift in `DESIGN_ISSUES.md` or `RISK_REGISTER.md` when intent and implementation disagree. | ||
| ## Target Artifacts | ||
| Unscoped/repo-level artifacts: | ||
| Unscoped/repo-level artifacts required by recon passes: | ||
@@ -46,3 +83,3 @@ ```text | ||
| Scoped artifacts, created only when a pass receives a focus argument: | ||
| Scoped artifacts, created only when a pass receives a focus argument. Safe-start-compatible scoped docs may contain additional intent/flow/test/validation artifacts; preserve them when present. | ||
@@ -56,3 +93,5 @@ ```text | ||
| REPO_INVENTORY.md | ||
| PROJECT_INTENT.md # preserve/update when present; create only when useful | ||
| ARCHITECTURE.md | ||
| DATA_FLOW.md # preserve/update when present; create only when useful | ||
| DATA_MODEL.md | ||
@@ -64,6 +103,10 @@ INVARIANTS.md | ||
| CHANGE_GUIDE.md | ||
| TESTING_STRATEGY.md # preserve/update when present; create only when useful | ||
| VALIDATION_BASELINE.md # preserve/update when present; create only when useful | ||
| CONTRACTS.md | ||
| by-domain/<domain-slug>/ | ||
| README.md # optional local index for large/complex scopes | ||
| PROJECT_INTENT.md # preserve/update when present; create only when useful | ||
| ARCHITECTURE.md | ||
| DATA_FLOW.md # preserve/update when present; create only when useful | ||
| DATA_MODEL.md | ||
@@ -75,2 +118,4 @@ INVARIANTS.md | ||
| CHANGE_GUIDE.md | ||
| TESTING_STRATEGY.md # preserve/update when present; create only when useful | ||
| VALIDATION_BASELINE.md # preserve/update when present; create only when useful | ||
| CONTRACTS.md | ||
@@ -118,3 +163,3 @@ ``` | ||
| - Docs path | ||
| - Status: `partial` / `current` / `stale` / `deprecated` | ||
| - Status: `planned` / `partial` / `current` / `stale` / `deprecated` | ||
| - Owns | ||
@@ -291,3 +336,3 @@ - External contracts | ||
| Read first: `docs/agent/ARCHITECTURE.md`, `docs/agent/INVARIANTS.md`, `docs/agent/DATA_MODEL.md`, `docs/agent/DEPENDENCY_RULES.md`, `docs/agent/RISK_REGISTER.md`, `docs/agent/DESIGN_ISSUES.md`. | ||
| Read first: `docs/agent/ARCHITECTURE.md`, `docs/agent/INVARIANTS.md`, `docs/agent/DATA_MODEL.md`, `docs/agent/DEPENDENCY_RULES.md`, `docs/agent/RISK_REGISTER.md`, `docs/agent/DESIGN_ISSUES.md`; when present, also read `docs/agent/PROJECT_INTENT.md`, `docs/agent/DATA_FLOW.md`, `docs/agent/TESTING_STRATEGY.md`, and `docs/agent/VALIDATION_BASELINE.md` only for operating guidance that affects future changes. | ||
@@ -319,3 +364,3 @@ Task: write/update root `AGENTS.md`. | ||
| Read first: `docs/agent/ARCHITECTURE.md`, `docs/agent/DATA_MODEL.md`, `docs/agent/INVARIANTS.md`, `docs/agent/DEPENDENCY_RULES.md`. | ||
| Read first: `docs/agent/ARCHITECTURE.md`, `docs/agent/DATA_MODEL.md`, `docs/agent/INVARIANTS.md`, `docs/agent/DEPENDENCY_RULES.md`; when present, also read `docs/agent/PROJECT_INTENT.md`, `docs/agent/DATA_FLOW.md`, `docs/agent/TESTING_STRATEGY.md`, and `docs/agent/VALIDATION_BASELINE.md` for scope, data-flow tracing, test guidance, and validation commands. | ||
@@ -333,3 +378,3 @@ Task: write/update `docs/agent/CHANGE_GUIDE.md`, or scoped `CHANGE_GUIDE.md` when focus is provided. | ||
| - How to avoid architecture drift | ||
| - Documentation update checklist | ||
| - Documentation update checklist, including compatible safe-start docs when present | ||
| - Final verification checklist | ||
@@ -346,2 +391,3 @@ | ||
| - Reconcile contradictions; do not silently delete disagreement evidence. | ||
| - Preserve compatible safe-start docs (`PROJECT_INTENT.md`, `DATA_FLOW.md`, `TESTING_STRATEGY.md`, `VALIDATION_BASELINE.md`) at top-level and scoped paths when present; update status/evidence headers and cross-links when source evidence proves them current/stale. | ||
| - Read `docs/agent/SCOPES.md` first when present; use it to select relevant scoped summaries and changed/relevant scoped docs. | ||
@@ -356,2 +402,3 @@ - When scoped passes disagree, resolve from source evidence where possible, assign/clarify ownership for shared contracts where evidence supports it, or record the disagreement as a drift risk / `Known Unknown` with cited evidence. | ||
| - Ensure `RISK_REGISTER.md` contains actionable risks. | ||
| - Ensure `VALIDATION_BASELINE.md`, when present, names commands and blockers rather than broad strategy. | ||
| - Preserve uncertainty markers where evidence incomplete. | ||
@@ -378,3 +425,3 @@ - Add `Known Unknowns` where useful. | ||
| Read first: `docs/agent/RISK_REGISTER.md`, `docs/agent/INVARIANTS.md`, `docs/agent/DATA_MODEL.md`, `docs/agent/CHANGE_GUIDE.md`. | ||
| Read first: `docs/agent/RISK_REGISTER.md`, `docs/agent/INVARIANTS.md`, `docs/agent/DATA_MODEL.md`, `docs/agent/CHANGE_GUIDE.md`; when present, also read `docs/agent/TESTING_STRATEGY.md` and `docs/agent/VALIDATION_BASELINE.md` for test type and command guidance. | ||
@@ -381,0 +428,0 @@ Task: select top 3–5 risks to convert into tests first. |
@@ -6,10 +6,15 @@ # Semantic Docs Update Rules | ||
| Update relevant top-level or scoped docs for changes to: | ||
| - architecture or dependency direction | ||
| - data model, persisted/serialized formats, schemas, API contracts, or shared types | ||
| - invariants, lifecycle rules, state transitions, validation, or ownership rules | ||
| - side-effect boundaries | ||
| - public/internal contracts between modules/packages/services | ||
| - known risks or risk status | ||
| - safe-change workflow guidance discovered during implementation | ||
| - `PROJECT_INTENT.md`: project intent, scope, non-goals, users, journeys, or constraints | ||
| - `REPO_INVENTORY.md`: entry points, validation commands, directories, or external boundaries | ||
| - `ARCHITECTURE.md` / `DEPENDENCY_RULES.md`: architecture or dependency direction | ||
| - `DATA_FLOW.md`: transformation pipelines, side-effect flows, or error states | ||
| - `DATA_MODEL.md`: persisted/serialized formats, schemas, API contracts, or shared types | ||
| - `INVARIANTS.md`: lifecycle rules, state transitions, validation, or ownership rules | ||
| - `CONTRACTS.md`: public/internal contracts between modules/packages/services | ||
| - `TESTING_STRATEGY.md` / `VALIDATION_BASELINE.md`: test approach or known-good validation commands | ||
| - `RISK_REGISTER.md` / `DESIGN_ISSUES.md`: known risks, design issues, deferred decisions, or risk status | ||
| - `CHANGE_GUIDE.md`: safe-change workflow guidance discovered during implementation | ||
| When artifact headers exist, update `Status`, `Evidence`, or `Last validated` only when the change or validation materially affects planned/observed/currentness. | ||
| Do not update docs for: | ||
@@ -25,3 +30,4 @@ - purely mechanical edits | ||
| - update consumer docs only for local usage/risk changes | ||
| - update `SCOPES.md` if scope status, ownership, contracts, or evidence changed | ||
| - update top-level docs only if repo-level summary/guidance changed | ||
| - leave broader reconciliation for codebase-recon Pass 8 when multiple scopes are affected |
@@ -8,5 +8,9 @@ # Universal Preflight | ||
| - `docs/agent/SCOPES.md` if present; then apply `references/scoped-docs.md` | ||
| - matching scoped `REPO_INVENTORY.md` or top-level `docs/agent/REPO_INVENTORY.md` if present, for entry points, commands, and external boundaries | ||
| - matching scoped `VALIDATION_BASELINE.md` or top-level `docs/agent/VALIDATION_BASELINE.md` if present, for known-good validation commands and blockers | ||
| If scoped docs match the task, read nearest scoped `README.md` only if present and only task-relevant scoped docs first. Then read only missing or repo-wide top-level docs relevant to task: | ||
| - `docs/agent/PROJECT_INTENT.md` or scoped `PROJECT_INTENT.md` for scope, non-goals, users, journeys, and product constraints | ||
| - `docs/agent/ARCHITECTURE.md` or scoped `ARCHITECTURE.md` for module/flow changes | ||
| - `docs/agent/DATA_FLOW.md` or scoped `DATA_FLOW.md` for user journeys, pipelines, transformations, side effects, and error states | ||
| - `docs/agent/DATA_MODEL.md` or scoped `DATA_MODEL.md` for data changes | ||
@@ -17,4 +21,7 @@ - `docs/agent/INVARIANTS.md` or scoped `INVARIANTS.md` for rule-sensitive changes | ||
| - `docs/agent/DESIGN_ISSUES.md` or scoped `DESIGN_ISSUES.md` for refactoring/design work | ||
| - `docs/agent/TESTING_STRATEGY.md` or scoped `TESTING_STRATEGY.md` for test design and validation approach | ||
| - scoped `CONTRACTS.md` files for touched cross-scope APIs, shared types, schemas, events, generated clients, or persistence boundaries | ||
| When artifact headers exist, treat `planned` docs as intent and verify implementation-sensitive claims against source evidence. | ||
| Before editing code, produce: | ||
@@ -21,0 +28,0 @@ 1. Task classification: bug fix / feature / refactoring / risk-fix / test-only / docs-only |
@@ -14,3 +14,6 @@ # Scoped Docs Discovery | ||
| - read only task-relevant scoped docs, then top-level docs as fallback for missing categories or repo-wide rules | ||
| - standard scoped docs may include `REPO_INVENTORY.md`, `ARCHITECTURE.md`, `DATA_MODEL.md`, `INVARIANTS.md`, `DEPENDENCY_RULES.md`, `DESIGN_ISSUES.md`, `RISK_REGISTER.md`, `CHANGE_GUIDE.md`, and `CONTRACTS.md` | ||
| - safe-start scoped docs may also include `PROJECT_INTENT.md`, `DATA_FLOW.md`, `TESTING_STRATEGY.md`, and `VALIDATION_BASELINE.md`; read them only when task-relevant | ||
| - before trusting a path scope, verify the scoped source path still exists; if not, treat scoped docs as historical/stale and fall back to top-level/source evidence | ||
| - when scoped docs are marked `planned`, use them as intent and verify implementation-sensitive claims against source evidence | ||
| - if multiple scopes match with equal confidence, read all relevant scope summaries and note ambiguity in preflight | ||
@@ -17,0 +20,0 @@ |
@@ -26,2 +26,35 @@ --- | ||
| ## Artifact Compatibility Contract | ||
| Safe-change accepts artifacts produced by both `safe-start` and `codebase-recon`. | ||
| Canonical repo-level docs may include: | ||
| ```text | ||
| docs/agent/ | ||
| REPO_INVENTORY.md | ||
| PROJECT_INTENT.md | ||
| ARCHITECTURE.md | ||
| DATA_FLOW.md | ||
| DATA_MODEL.md | ||
| INVARIANTS.md | ||
| DEPENDENCY_RULES.md | ||
| DESIGN_ISSUES.md | ||
| RISK_REGISTER.md | ||
| CHANGE_GUIDE.md | ||
| TESTING_STRATEGY.md | ||
| VALIDATION_BASELINE.md | ||
| SCOPES.md | ||
| ``` | ||
| Respect artifact headers when present: | ||
| ```text | ||
| Status: current | partial | stale | ||
| Evidence: planned | observed | mixed | ||
| Last validated: unknown | <date> | ||
| ``` | ||
| Treat `planned` docs as design intent, not source evidence. Verify against code before relying on them for implementation-sensitive claims. | ||
| ## Scoped Docs | ||
@@ -47,5 +80,9 @@ | ||
| - `docs/agent/SCOPES.md` if present; then apply `references/scoped-docs.md` | ||
| - matching scoped `REPO_INVENTORY.md` or top-level `docs/agent/REPO_INVENTORY.md` if present, for entry points, commands, and boundaries | ||
| - matching scoped `VALIDATION_BASELINE.md` or top-level `docs/agent/VALIDATION_BASELINE.md` if present, for known-good validation commands and blockers | ||
| Read only docs relevant to task: | ||
| - project intent for scope, user-goal, non-goal, or product-sensitive changes | ||
| - architecture docs for module/flow changes | ||
| - data-flow docs for changes to user journeys, pipelines, transformations, or side effects | ||
| - data model docs for data/schema/API/type changes | ||
@@ -56,2 +93,3 @@ - invariant docs for rule-sensitive changes | ||
| - design issues for refactoring/design work | ||
| - testing strategy for new/changed tests or validation approach | ||
| - scoped `CONTRACTS.md` files for touched cross-scope APIs, shared types, schemas, events, generated clients, or persistence boundaries | ||
@@ -58,0 +96,0 @@ |
+137
-18
@@ -39,6 +39,8 @@ --- | ||
| ## Target Artifacts | ||
| ## Artifact Compatibility Contract | ||
| Create/update these before or during scaffold as appropriate: | ||
| Safe-start artifacts must be compatible with later `safe-change` work and with `codebase-recon` consolidation. | ||
| Baseline repo-level artifacts: | ||
| ```text | ||
@@ -50,11 +52,13 @@ README.md | ||
| docs/agent/ | ||
| REPO_INVENTORY.md | ||
| PROJECT_INTENT.md | ||
| ARCHITECTURE.md | ||
| DATA_FLOW.md | ||
| DATA_MODEL.md | ||
| INVARIANTS.md | ||
| ARCHITECTURE.md | ||
| DEPENDENCY_RULES.md | ||
| DESIGN_ISSUES.md | ||
| RISK_REGISTER.md | ||
| CHANGE_GUIDE.md | ||
| TESTING_STRATEGY.md | ||
| CHANGE_GUIDE.md | ||
| VALIDATION_BASELINE.md | ||
@@ -74,2 +78,12 @@ adr/ | ||
| Artifact header guidance for durable docs: | ||
| ```text | ||
| Status: current | partial | stale | ||
| Evidence: planned | observed | mixed | ||
| Last validated: unknown | <date> | ||
| ``` | ||
| Use `planned` before scaffold/implementation exists. Update to `observed` or `mixed` after validation against real files and commands. | ||
| Rules: | ||
@@ -80,3 +94,80 @@ - Project operating instructions stay at root `AGENTS.md`. | ||
| - Docs should describe durable semantics, not tutorial prose, except in Freshman mode where short teaching notes are allowed. | ||
| - Avoid duplicate source-of-truth facts: `AGENTS.md` stays short and operational; semantic docs hold durable detail; `CHANGE_GUIDE.md` holds workflow. | ||
| ## Scope/Focus Arguments | ||
| Prompt arguments may include a target, focus, scope, domain, service, package, app, tool, or environment. Use these to limit a pass to one planned boundary while keeping repo-level docs as summary/fallback. | ||
| When a scope/focus is provided: | ||
| - define whether it is path-based (`apps/web`, `packages/sdk`, `infra/prod`) or domain-based (`billing`, `identity`, `plugin-system`) | ||
| - create/update `docs/agent/SCOPES.md` before writing scoped docs | ||
| - write detailed findings to matching scoped artifacts, not only top-level docs | ||
| - update top-level docs only with stable repo-level summary or cross-scope guidance | ||
| - identify owner/consumer contracts when the scope exposes APIs, shared types, events, schemas, generated clients, persistence formats, deployment interfaces, CLIs, SDKs, plugins, or infra modules | ||
| ## Scoped Artifacts | ||
| Use scoped safe-start artifacts for monorepos, enterprise-grade systems, dev-tools platforms, infra/IaC repos, multi-service systems, or any project where one repo-level summary would hide ownership boundaries. | ||
| Scoped artifacts mirror `codebase-recon` scope layout: | ||
| ```text | ||
| docs/agent/ | ||
| SCOPES.md | ||
| scopes/ | ||
| by-path/<repo-relative-path>/ | ||
| README.md # optional local index for large/complex scopes | ||
| REPO_INVENTORY.md | ||
| PROJECT_INTENT.md | ||
| ARCHITECTURE.md | ||
| DATA_FLOW.md | ||
| DATA_MODEL.md | ||
| INVARIANTS.md | ||
| DEPENDENCY_RULES.md | ||
| DESIGN_ISSUES.md | ||
| RISK_REGISTER.md | ||
| CHANGE_GUIDE.md | ||
| TESTING_STRATEGY.md | ||
| VALIDATION_BASELINE.md | ||
| CONTRACTS.md # when scope owns cross-scope APIs/schemas/events | ||
| by-domain/<domain-slug>/ | ||
| README.md # optional local index for large/complex scopes | ||
| PROJECT_INTENT.md | ||
| ARCHITECTURE.md | ||
| DATA_FLOW.md | ||
| DATA_MODEL.md | ||
| INVARIANTS.md | ||
| DEPENDENCY_RULES.md | ||
| DESIGN_ISSUES.md | ||
| RISK_REGISTER.md | ||
| CHANGE_GUIDE.md | ||
| TESTING_STRATEGY.md | ||
| VALIDATION_BASELINE.md | ||
| CONTRACTS.md | ||
| ``` | ||
| `docs/agent/SCOPES.md` is required when scoped artifacts exist. Suggested columns: | ||
| - Scope | ||
| - Kind: `path` / `domain` | ||
| - Docs path | ||
| - Status: `planned` / `partial` / `current` / `stale` / `deprecated` | ||
| - Owns | ||
| - External contracts | ||
| - Last validated evidence | ||
| When to introduce scopes: | ||
| - monorepo with apps/packages/services under separate paths | ||
| - enterprise codebase with independently owned domains or bounded contexts | ||
| - dev-tools repo with CLI, SDK, server, extension, plugin, or template surfaces | ||
| - infra repo with environments, modules, deployment pipelines, policy, or runtime ops boundaries | ||
| - cross-scope contracts exist: APIs, shared types, events, generated clients, persistence formats, deployment interfaces | ||
| Scope rules: | ||
| - Prefer `by-path` when source path is known or will be scaffolded. | ||
| - Use `by-domain` for business/platform domains before final paths exist. | ||
| - Every cross-scope contract should have one owner scope documented in `CONTRACTS.md`. | ||
| - Consumer scopes link to owner contracts and record local usage/risk only. | ||
| - Top-level docs remain repo-level summaries and fallback guidance; scope docs hold detailed local truth. | ||
| - Safe-start handoff must explain whether future `safe-change` work should use top-level docs, scoped docs, or both. | ||
| ## Execution Modes | ||
@@ -107,7 +198,7 @@ | ||
| In all-in-one mode: | ||
| 1. Capture intent and guidance level. | ||
| 1. Capture intent, guidance level, and whether scoped artifacts are needed. | ||
| 2. Produce data-first design and scaffold plan. | ||
| 3. Stop for approval before writing files unless user explicitly requested implementation. | ||
| 4. Scaffold, validate, implement first vertical slice if approved/requested. | ||
| 5. Report validation and handoff status. | ||
| 5. Report validation and handoff status, including whether future work should use scoped docs. | ||
@@ -133,5 +224,8 @@ ## Approval Gates | ||
| - `docs/agent/PROJECT_INTENT.md` | ||
| - `docs/agent/REPO_INVENTORY.md` with planned/observed scaffold inventory, entry points, validation commands, and external boundaries | ||
| - `docs/agent/SCOPES.md` when scoped artifacts are needed | ||
| - matching scoped `PROJECT_INTENT.md` / `REPO_INVENTORY.md` when a focus or scope is in play | ||
| - initial `README.md` summary if creating files now | ||
| Required sections: | ||
| Required sections for `PROJECT_INTENT.md`: | ||
| - Product goal | ||
@@ -145,5 +239,16 @@ - Target users | ||
| - Guidance level | ||
| - Scope model: unscoped repo, path scopes, domain scopes, or deferred | ||
| - Assumptions | ||
| - Open questions | ||
| Required sections for `REPO_INVENTORY.md`: | ||
| - Planned/observed project summary | ||
| - Planned/observed build and validation commands | ||
| - Planned/observed entry points | ||
| - Planned/observed major directories | ||
| - External dependencies/boundaries | ||
| - Scope registry summary when scoped artifacts exist | ||
| - Unknowns | ||
| - Next recommended design/scaffold targets | ||
| ## Pass 2 — Data Flow Design | ||
@@ -153,3 +258,3 @@ | ||
| Read first: `docs/agent/PROJECT_INTENT.md` if present. | ||
| Read first: `docs/agent/PROJECT_INTENT.md` if present; `docs/agent/SCOPES.md` and matching scoped intent/inventory when scoped artifacts are in play. | ||
@@ -162,2 +267,3 @@ Task: design data-first system shape. | ||
| - `docs/agent/INVARIANTS.md` | ||
| - matching scoped `DATA_FLOW.md`, `DATA_MODEL.md`, and `INVARIANTS.md` when a focus or scope is in play | ||
@@ -182,3 +288,3 @@ Required sections: | ||
| Read first: project intent, data flow, data model, invariants. | ||
| Read first: project intent, data flow, data model, invariants, and `docs/agent/SCOPES.md` / matching scoped docs when scoped artifacts are in play. | ||
@@ -190,4 +296,6 @@ Task: choose initial architecture after data shape is known. | ||
| - `docs/agent/DEPENDENCY_RULES.md` | ||
| - `docs/agent/DESIGN_ISSUES.md` | ||
| - `docs/agent/RISK_REGISTER.md` | ||
| - `docs/agent/adr/0001-initial-architecture.md` | ||
| - matching scoped artifacts when a focus or scope is in play | ||
@@ -203,2 +311,3 @@ Required sections: | ||
| - Security/privacy basics | ||
| - Known design issues, deferred decisions, and drift risks | ||
| - Key risks and mitigations | ||
@@ -211,3 +320,3 @@ - ADR with context, decision, alternatives, consequences | ||
| Read first: intent, data flow/model, architecture, dependency rules. | ||
| Read first: intent, data flow/model, architecture, dependency rules, and `docs/agent/SCOPES.md` / matching scoped docs when scoped artifacts are in play. | ||
@@ -222,2 +331,3 @@ Task: create operational docs for future agents and developers. | ||
| - optional `docs/agent/CONTRACTS.md`, `SECURITY.md`, `DEPLOYMENT.md` | ||
| - matching scoped artifacts and owner `CONTRACTS.md` files when scoped artifacts are in play | ||
@@ -227,7 +337,8 @@ Required content: | ||
| - Architecture rules | ||
| - Data model rules | ||
| - Data flow and data model rules | ||
| - Invariants not to violate | ||
| - How to discover matching scoped docs through `docs/agent/SCOPES.md` when present | ||
| - How to add/modify features | ||
| - How to validate changes | ||
| - Documentation update rules | ||
| - Documentation update rules, including planned/observed/status header updates when useful | ||
| - Freshman-friendly command explanations when guidance level is Freshman | ||
@@ -239,3 +350,3 @@ | ||
| Read first: all prior design docs. | ||
| Read first: all prior design docs, including `docs/agent/SCOPES.md` and matching scoped docs when scoped artifacts are in play. | ||
@@ -270,6 +381,7 @@ Task: propose minimal file tree and tooling before writing project code. | ||
| Task: make baseline checks green before real feature depth. | ||
| Task: make baseline checks green before real feature depth. For scoped projects, validate repo-level commands plus independently runnable scope commands where practical. | ||
| Output/update: | ||
| - `docs/agent/VALIDATION_BASELINE.md` | ||
| - matching scoped `VALIDATION_BASELINE.md` for independently validated apps/packages/services/tools/infra scopes | ||
@@ -290,5 +402,5 @@ Required validations when applicable: | ||
| Read first: prior docs and validation baseline. | ||
| Read first: prior docs and validation baseline, including matching scoped docs when scoped artifacts are in play. | ||
| Task: implement one small end-to-end feature crossing real boundaries. | ||
| Task: implement one small end-to-end feature crossing real boundaries. In scoped projects, choose one scope or one owner/consumer contract path for the first slice unless the user explicitly asks for a broader enterprise scaffold. | ||
@@ -315,2 +427,5 @@ Slice should include: | ||
| - `docs/agent/RISK_REGISTER.md` | ||
| - `docs/agent/REPO_INVENTORY.md` | ||
| - `docs/agent/DESIGN_ISSUES.md` | ||
| - `docs/agent/SCOPES.md` when scoped artifacts exist | ||
| - optional `docs/agent/BACKLOG.md` | ||
@@ -320,7 +435,11 @@ | ||
| - root `AGENTS.md` exists and is operational | ||
| - docs/agent artifacts cover architecture, data, invariants, dependency rules, tests, risks | ||
| - `REPO_INVENTORY.md` exists and reflects planned vs observed scaffold state | ||
| - `DESIGN_ISSUES.md` exists, even if it says no known issues/deferred decisions | ||
| - docs/agent artifacts cover architecture, data flow, data model, invariants, dependency rules, tests, risks, validation baseline | ||
| - `CHANGE_GUIDE.md` links or points to `PROJECT_INTENT.md`, `DATA_FLOW.md`, `TESTING_STRATEGY.md`, and `VALIDATION_BASELINE.md` when relevant | ||
| - validation baseline commands are known and recently run | ||
| - first slice is implemented or explicitly deferred | ||
| - scoped docs exist when repo complexity warrants them, with `SCOPES.md` identifying owners and contracts | ||
| - next work items are small enough for `safe-change` | ||
| Final note should say whether future work should use `safe-change`, and which docs to read first. | ||
| Final note should say whether future work should use `safe-change`, whether scoped docs should be read, and which docs to read first. |
No alert changes
Improved metrics
- Total package byte prevSize
94261
24.49%- Number of package files
46
2.22%No dependency changes