🎩 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
+12
-0
@@ -15,2 +15,14 @@ # Changelog | ||
| ## [0.3.2] - 2026-05-19 | ||
| ### Added | ||
| - Added workflow context-budget and non-duplication guidance across safe-start, codebase-recon, safe-change, and architecture review. | ||
| - Added artifact ownership guidance to keep agent docs as source-of-truth shards or routers instead of redundant summaries. | ||
| ### Fixes | ||
| - Made `codebase-recon` create `VALIDATION_BASELINE.md` during inventory passes and `TESTING_STRATEGY.md` during risk-to-tests planning, including scoped equivalents when relevant. | ||
| - Added safe-change and architecture-review fallbacks when validation baseline or testing strategy docs are missing. | ||
| ## [0.3.1] - 2026-05-18 | ||
@@ -17,0 +29,0 @@ |
+1
-1
| { | ||
| "name": "pi-agent-codebase-workflows", | ||
| "version": "0.3.1", | ||
| "version": "0.3.2", | ||
| "description": "Pi skills and prompt templates for safe greenfield starts, codebase reconstruction, architecture-aware review, and safe changes.", | ||
@@ -5,0 +5,0 @@ "license": "MIT", |
@@ -47,2 +47,17 @@ --- | ||
| ## Context Budget and Non-Duplication | ||
| Review should not load every artifact by default. Read router docs needed to locate scope, then owner artifacts relevant to changed semantics. | ||
| Artifact ownership rules: | ||
| - `CHANGE_GUIDE.md` routes workflow; semantic truth lives in specific docs. | ||
| - `REPO_INVENTORY.md` maps files/entry points/command names; `VALIDATION_BASELINE.md` owns command status/blockers. | ||
| - `ARCHITECTURE.md` owns structure and side-effect boundaries; `DEPENDENCY_RULES.md` owns import/dependency direction. | ||
| - `DATA_FLOW.md` owns lifecycles and transformations; `DATA_MODEL.md` owns schemas/entities; `INVARIANTS.md` owns rules/forbidden states. | ||
| - `DESIGN_ISSUES.md` owns drift/deferred design problems; `RISK_REGISTER.md` owns failure modes and risk-tested fixes. | ||
| - `TESTING_STRATEGY.md` owns test approach/gaps; `VALIDATION_BASELINE.md` owns exact validation status. | ||
| - `SCOPES.md` routes to scoped docs; scoped docs own local detail, top-level docs hold repo-wide summary. | ||
| Flag review findings when a change duplicates detailed semantic truth across artifacts instead of updating the owner artifact and linking from router docs. | ||
| ## Scoped Docs Discovery | ||
@@ -76,3 +91,3 @@ | ||
| - 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 | ||
| - matching scoped `VALIDATION_BASELINE.md` or top-level `docs/agent/VALIDATION_BASELINE.md` when build/test/tooling/validation behavior changes; if absent, infer validation expectations from package/build files and note missing baseline only when relevant | ||
| - `docs/agent/PROJECT_INTENT.md` for scope, non-goals, users, journeys, or product-sensitive changes | ||
@@ -86,3 +101,3 @@ - `docs/agent/ARCHITECTURE.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 | ||
| - `docs/agent/TESTING_STRATEGY.md` for test coverage expectations and validation shape; if absent, infer from existing tests and mention missing strategy only when it materially affects review confidence | ||
| - scoped `CONTRACTS.md` files for touched cross-scope APIs, shared types, schemas, events, generated clients, or persistence boundaries | ||
@@ -110,2 +125,3 @@ - Prioritize correctness, architecture drift, data consistency, side-effect boundaries, public contracts, and tests. | ||
| - Are docs updated only for durable semantic changes? | ||
| - Are detailed facts placed in the owner artifact instead of duplicated across router/index docs? | ||
| - Are docs marked `planned` now backed by observed implementation, still valid as intent, or stale? | ||
@@ -112,0 +128,0 @@ |
@@ -45,4 +45,4 @@ --- | ||
| 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 | ||
| TESTING_STRATEGY.md # required baseline artifact; may state unknowns/gaps | ||
| VALIDATION_BASELINE.md # required baseline artifact; may state blockers/not run | ||
| adr/ | ||
@@ -62,2 +62,30 @@ 0001-observed-architecture.md | ||
| ## Context Budget and Non-Duplication | ||
| Each artifact should be either a source of truth for one semantic category or an index/router to other docs. Do not make every artifact a summary of every other artifact. | ||
| Artifact ownership: | ||
| - `AGENTS.md`: injected operating rules, forbidden shortcuts, validation expectations, and links only. | ||
| - `CHANGE_GUIDE.md`: workflow and doc-routing guide; link to semantic docs instead of repeating them. | ||
| - `SCOPES.md`: routing table for scoped docs; no detailed architecture or contract prose. | ||
| - `REPO_INVENTORY.md`: file tree, entry points, commands index, external boundaries; no architecture judgments. | ||
| - `PROJECT_INTENT.md`: product/user goals, non-goals, constraints, assumptions. | ||
| - `ARCHITECTURE.md`: components, boundaries, side-effect boundaries, high-level execution flows. | ||
| - `DEPENDENCY_RULES.md`: allowed/forbidden dependency direction and import boundaries. | ||
| - `DATA_FLOW.md`: input -> transformation -> output lifecycles, events, request paths, error states. | ||
| - `DATA_MODEL.md`: entities, schemas, IDs, relationships, persisted/serialized formats. | ||
| - `INVARIANTS.md`: rules, forbidden states, lifecycle constraints, enforcement locations. | ||
| - `DESIGN_ISSUES.md`: design drift, unresolved design problems, deferred decisions. | ||
| - `RISK_REGISTER.md`: failure modes with severity, evidence, failure scenario, suggested test/fix. | ||
| - `TESTING_STRATEGY.md`: test approach, coverage gaps, risk-to-test priorities. | ||
| - `VALIDATION_BASELINE.md`: exact commands, last status, blockers, next best checks. | ||
| - `CONTRACTS.md`: cross-scope APIs, schemas, events, generated clients, persistence/deployment interfaces. | ||
| Duplication rules: | ||
| - Prefer links/references over copied detail. | ||
| - If `VALIDATION_BASELINE.md` exists, `REPO_INVENTORY.md` may list command names but should link to baseline for status/blockers. | ||
| - If `TESTING_STRATEGY.md` exists, `CHANGE_GUIDE.md` should link to it for testing details. | ||
| - Top-level docs summarize stable repo-wide truths; scoped docs hold local detail. | ||
| - If a required artifact has little evidence, create a compact stub with `No known ...`, `Unknown`, or `Not yet validated`, not boilerplate prose. | ||
| ## Target Artifacts | ||
@@ -80,2 +108,4 @@ | ||
| CHANGE_GUIDE.md | ||
| TESTING_STRATEGY.md | ||
| VALIDATION_BASELINE.md | ||
| adr/ | ||
@@ -103,4 +133,4 @@ 0001-observed-architecture.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 | ||
| TESTING_STRATEGY.md # required when Pass 10 runs for this scope | ||
| VALIDATION_BASELINE.md # required when Pass 1 runs for this scope | ||
| CONTRACTS.md | ||
@@ -118,4 +148,4 @@ by-domain/<domain-slug>/ | ||
| 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 | ||
| TESTING_STRATEGY.md # required when Pass 10 runs for this scope | ||
| VALIDATION_BASELINE.md # required when Pass 1 runs for this scope | ||
| CONTRACTS.md | ||
@@ -225,3 +255,3 @@ ``` | ||
| Task: write/update `docs/agent/REPO_INVENTORY.md`, or scoped `REPO_INVENTORY.md` when focus is provided. | ||
| Task: write/update `docs/agent/REPO_INVENTORY.md` and `docs/agent/VALIDATION_BASELINE.md`, or scoped `REPO_INVENTORY.md` / `VALIDATION_BASELINE.md` when focus is provided. | ||
@@ -232,4 +262,5 @@ Rules: | ||
| - Inspect build/config/package files, directory tree, entry points, tests, validation commands, external boundaries. | ||
| - Create `VALIDATION_BASELINE.md` even if commands cannot be run; record exact unknowns, blockers, and next best checks. | ||
| Output sections: | ||
| `REPO_INVENTORY.md` output sections: | ||
| - Project summary | ||
@@ -243,2 +274,11 @@ - Build/test commands | ||
| `VALIDATION_BASELINE.md` output sections: | ||
| - Install/bootstrap command(s) | ||
| - Format/lint command(s) | ||
| - Typecheck/build command(s) | ||
| - Test command(s) | ||
| - Runtime/smoke command(s) | ||
| - Last run status: run / not run / blocked | ||
| - Blockers and next best checks | ||
| ## Pass 2 — Architecture Reconstruction | ||
@@ -345,2 +385,3 @@ | ||
| - Link to deeper docs; do not duplicate them. | ||
| - Treat `AGENTS.md` as an index of rules and pointers, not a semantic artifact dump. | ||
| - Focus on rules that prevent drift and bugs. | ||
@@ -400,4 +441,6 @@ - Include design/implementation/verification workflow. | ||
| - Ensure `INVARIANTS.md` contains rules, not implementation notes. | ||
| - Ensure `RISK_REGISTER.md` contains actionable risks. | ||
| - Ensure `VALIDATION_BASELINE.md`, when present, names commands and blockers rather than broad strategy. | ||
| - Ensure `RISK_REGISTER.md` contains actionable risks, not generic design concerns owned by `DESIGN_ISSUES.md`. | ||
| - Ensure `CHANGE_GUIDE.md` routes readers to source-of-truth docs instead of duplicating them. | ||
| - Ensure `VALIDATION_BASELINE.md` exists after repo-level Pass 1 has run and names commands/blockers rather than broad strategy. | ||
| - Ensure `TESTING_STRATEGY.md` exists after repo-level Pass 10 has run and names observed test structure, gaps, and risk-to-test priorities. | ||
| - Preserve uncertainty markers where evidence incomplete. | ||
@@ -424,6 +467,8 @@ - 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`; when present, also read `docs/agent/TESTING_STRATEGY.md` and `docs/agent/VALIDATION_BASELINE.md` for test type and command guidance. | ||
| Read first: `docs/agent/RISK_REGISTER.md`, `docs/agent/INVARIANTS.md`, `docs/agent/DATA_MODEL.md`, `docs/agent/CHANGE_GUIDE.md`, `docs/agent/TESTING_STRATEGY.md`, and `docs/agent/VALIDATION_BASELINE.md`. | ||
| Task: select top 3–5 risks to convert into tests first. | ||
| Task: write/update `docs/agent/TESTING_STRATEGY.md`, or scoped `TESTING_STRATEGY.md` when focus is provided, and select top 3–5 risks to convert into tests first. | ||
| Create `TESTING_STRATEGY.md` even if test coverage is sparse or unknown; record observed test types, gaps, risk-based priorities, and recommended next tests. | ||
| Selection criteria: | ||
@@ -445,2 +490,10 @@ - high severity | ||
| `TESTING_STRATEGY.md` output sections: | ||
| - Observed test structure | ||
| - Existing test types and commands | ||
| - Coverage gaps around invariants and risks | ||
| - Recommended test strategy | ||
| - Risk-to-test priorities | ||
| - Known blockers | ||
| Do not write production code in this pass. |
@@ -19,2 +19,8 @@ # Semantic Docs Update Rules | ||
| Non-duplication rules: | ||
| - Update the owner artifact first; update router/index docs only with links or short pointers. | ||
| - Do not copy detailed architecture into `CHANGE_GUIDE.md` or `AGENTS.md`. | ||
| - Do not copy scoped-local details into top-level docs unless they changed repo-wide guidance. | ||
| - If multiple docs mention the same concept, keep only one detailed source of truth and replace other copies with references. | ||
| Do not update docs for: | ||
@@ -21,0 +27,0 @@ - purely mechanical edits |
@@ -9,3 +9,3 @@ # Universal Preflight | ||
| - 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 | ||
| - matching scoped `VALIDATION_BASELINE.md` or top-level `docs/agent/VALIDATION_BASELINE.md` if present, for known-good validation commands and blockers; if absent, derive validation commands from `REPO_INVENTORY.md`, package/build files, and test config, and note missing baseline in preflight | ||
@@ -21,3 +21,3 @@ 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/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 | ||
| - `docs/agent/TESTING_STRATEGY.md` or scoped `TESTING_STRATEGY.md` for test design and validation approach; if absent, infer from existing tests and note missing strategy in preflight | ||
| - scoped `CONTRACTS.md` files for touched cross-scope APIs, shared types, schemas, events, generated clients, or persistence boundaries | ||
@@ -27,2 +27,9 @@ | ||
| Context budget rules: | ||
| - Do not read every canonical artifact by default. | ||
| - Read owner artifact for the changed semantic category, plus router docs needed to find it. | ||
| - Prefer scoped docs for local detail and top-level docs for repo-wide fallback. | ||
| - If a needed owner artifact is absent, infer from source evidence and note missing artifact in preflight. | ||
| - Do not duplicate findings across docs during update planning; update the owner artifact and link from router docs. | ||
| Before editing code, produce: | ||
@@ -29,0 +36,0 @@ 1. Task classification: bug fix / feature / refactoring / risk-fix / test-only / docs-only |
@@ -59,2 +59,6 @@ --- | ||
| ## Context Budget and Non-Duplication | ||
| Do not read or update every artifact by default. Read only docs relevant to task category, scope, and risk. During preflight, apply `references/preflight.md`; during semantic docs updates, apply `references/docs-update.md`. | ||
| ## Scoped Docs | ||
@@ -81,3 +85,3 @@ | ||
| - 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 | ||
| - matching scoped `VALIDATION_BASELINE.md` or top-level `docs/agent/VALIDATION_BASELINE.md` if present, for known-good validation commands and blockers; if absent, derive validation commands from `REPO_INVENTORY.md`, package/build files, and test config, and note missing baseline in preflight | ||
@@ -93,3 +97,3 @@ Read only docs relevant to task: | ||
| - design issues for refactoring/design work | ||
| - testing strategy for new/changed tests or validation approach | ||
| - testing strategy for new/changed tests or validation approach; if `TESTING_STRATEGY.md` is absent, infer from existing tests and note missing strategy in preflight | ||
| - scoped `CONTRACTS.md` files for touched cross-scope APIs, shared types, schemas, events, generated clients, or persistence boundaries | ||
@@ -96,0 +100,0 @@ |
@@ -93,2 +93,30 @@ --- | ||
| ## Context Budget and Non-Duplication | ||
| Each artifact should be either a source of truth for one semantic category or an index/router to other docs. Do not make every artifact a summary of every other artifact. | ||
| Artifact ownership: | ||
| - `AGENTS.md`: injected operating rules, forbidden shortcuts, validation expectations, and links only. | ||
| - `CHANGE_GUIDE.md`: workflow and doc-routing guide; link to semantic docs instead of repeating them. | ||
| - `SCOPES.md`: routing table for scoped docs; no detailed architecture or contract prose. | ||
| - `REPO_INVENTORY.md`: file tree, entry points, commands index, external boundaries; no architecture judgments. | ||
| - `PROJECT_INTENT.md`: product/user goals, non-goals, constraints, assumptions. | ||
| - `ARCHITECTURE.md`: components, boundaries, side-effect boundaries, high-level execution flows. | ||
| - `DEPENDENCY_RULES.md`: allowed/forbidden dependency direction and import boundaries. | ||
| - `DATA_FLOW.md`: input -> transformation -> output lifecycles, events, request paths, error states. | ||
| - `DATA_MODEL.md`: entities, schemas, IDs, relationships, persisted/serialized formats. | ||
| - `INVARIANTS.md`: rules, forbidden states, lifecycle constraints, enforcement locations. | ||
| - `DESIGN_ISSUES.md`: design drift, unresolved design problems, deferred decisions. | ||
| - `RISK_REGISTER.md`: failure modes with severity, evidence, failure scenario, suggested test/fix. | ||
| - `TESTING_STRATEGY.md`: test approach, coverage gaps, risk-to-test priorities. | ||
| - `VALIDATION_BASELINE.md`: exact commands, last status, blockers, next best checks. | ||
| - `CONTRACTS.md`: cross-scope APIs, schemas, events, generated clients, persistence/deployment interfaces. | ||
| Duplication rules: | ||
| - Prefer links/references over copied detail. | ||
| - If `VALIDATION_BASELINE.md` exists, `REPO_INVENTORY.md` may list command names but should link to baseline for status/blockers. | ||
| - If `TESTING_STRATEGY.md` exists, `CHANGE_GUIDE.md` should link to it for testing details. | ||
| - Top-level docs summarize stable repo-wide truths; scoped docs hold local detail. | ||
| - If a required artifact has little content, create a compact stub with `No known ...`, `Unknown`, or `Not yet validated`, not boilerplate prose. | ||
| ## Scope/Focus Arguments | ||
@@ -95,0 +123,0 @@ |
No alert changes
Improved metrics
- Total package byte prevSize
103543
9.85%No dependency changes