🎩 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
| --- | ||
| description: "Validate structured YAML docs" | ||
| argument-hint: "[scope|docs-root|diff]" | ||
| --- | ||
| Load `/skill:structured-doc-validate`, resolve `<docs-root>` exactly per that skill (canonicalize `workspace_root`; if repo-local `<workspace_root>/docs/agent/api` does not exist, strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`), then read `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only schemas for artifacts being validated. Validate schema shape, shared schema coverage for canonical artifact files, reference integrity, evidence validity, coverage, and granularity. Treat missing now-required fields in legacy artifacts as schema failures, not compatibility notes. Read-only: do not edit code or artifacts unless explicitly asked to repair. Focus: $ARGUMENTS. |
| --- | ||
| name: structured-doc-validate | ||
| description: Validate canonical structured YAML artifacts for schema shape, reference integrity, evidence quality, coverage, and granularity. Read-only by default; no legacy prose docs. | ||
| --- | ||
| # Structured Docs Validation | ||
| Goal: audit canonical structured YAML artifacts so agents can trust, repair, or safely avoid stale project context. | ||
| ## Structured Artifact API Contract | ||
| Legacy prose artifacts are deprecated. Do not create, update, or rely on `docs/agent/*.md`, scoped prose docs, or generated human-readable Markdown views. Use structured YAML as the source of truth. Root `AGENTS.md` is only harness interoperability output from workflows that explicitly produce it. | ||
| Resolved structured docs root: | ||
| Treat `docs/agent/api` as a logical layout rooted at a resolved structured docs root, not a fixed repo path. | ||
| Resolution rules: | ||
| 1. Resolve `workspace_root` with `git rev-parse --show-toplevel 2>/dev/null` or fallback to `pwd`. | ||
| 2. Canonicalize `workspace_root` before fingerprinting when possible (`realpath`, `pwd -P`, `Path(...).resolve()`, or equivalent). | ||
| 3. `structured-doc-validate` reads repo-local only when `<workspace_root>/docs/agent/api` already exists. | ||
| 4. Otherwise read the global overlay root: `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. | ||
| 5. Compute `<workspace-fingerprint>` exactly from canonical `workspace_root`: strip one leading slash/backslash, replace every slash, backslash, and colon with `-`, then wrap with `--`. | ||
| 6. Example: `/data/data/com.termux/files/home/CodeProjects/pi-mono` -> `--data-data-com.termux-files-home-CodeProjects-pi-mono--`. | ||
| 7. Do not create new repo-local structured docs in unadopted repos unless the user explicitly asks for repo-local adoption there. | ||
| Logical structured layout under the resolved docs root: | ||
| ```text | ||
| repo/ | ||
| scopes.yaml | ||
| repo-inventory.yaml | ||
| project-intent.yaml | ||
| architecture.yaml | ||
| data-flow.yaml | ||
| data-model.yaml | ||
| invariants.yaml | ||
| dependency-rules.yaml | ||
| design-issues.yaml | ||
| risk-register.yaml | ||
| change-guide.yaml | ||
| testing-strategy.yaml | ||
| validation-baseline.yaml | ||
| contracts.yaml | ||
| adr.yaml | ||
| agent-operating-guide.yaml | ||
| scopes/ | ||
| by-path/<repo-relative-path>/... | ||
| by-domain/<slug>/... | ||
| ``` | ||
| Every structured artifact should conform to `../_shared/references/schemas/common.schema.json` plus its artifact-specific schema. Stable IDs include `scope:*`, `component:*`, `entity:*`, `invariant:*`, `risk:*`, `contract:*`, `flow:*`, `command:*`, `issue:*`, `adr:*`, and `testplan:*`. | ||
| ## Runtime Schema Loading | ||
| When validating structured artifacts, read `../_shared/references/artifact-api.md` first. Then read only the shared skill package schemas needed for artifacts being validated: | ||
| - `../_shared/references/schemas/common.schema.json` | ||
| - `../_shared/references/schemas/<artifact-file-base>.schema.json` | ||
| Do not read all schemas unless the validation target is the whole docs root. Do not use templates. Schemas are runtime API contracts; project docs outside the shared runtime refs are maintainer aids unless the user asks about this package itself. | ||
| ## Invocation | ||
| Use this skill directly or use `/validate-structured-docs` as the prompt-template shortcut. | ||
| Supported tasks: | ||
| - Validate structured docs for this repo/docs root. | ||
| - Audit docs after this diff. | ||
| - Check whether docs are granular enough for agent workflows. | ||
| - Find stale evidence or invalid refs. | ||
| - Report documentation quality without editing artifacts. | ||
| ## Rules | ||
| - Read-only by default. Do not edit code or artifacts unless the user explicitly asks for repair. | ||
| - Do not read legacy prose Markdown docs. | ||
| - Resolve `<docs-root>` exactly before reading artifacts. | ||
| - If a focus is provided, read `<docs-root>/repo/scopes.yaml` first when present and select matching scope artifacts by longest path prefix or explicit domain match. | ||
| - If no focus is provided, validate repo-level artifacts first, then scoped artifacts as context budget allows. | ||
| - Prefer exact, evidence-backed findings over broad opinions. | ||
| - Broken schemas, missing shared schema coverage for canonical artifact files, parse failures, and dangling refs are errors. Fuzzy evidence, coverage, and granularity concerns are warnings unless they block safe use. | ||
| - If structured artifacts predate newer schema requirements, missing now-required fields are schema errors, not compatibility notes. | ||
| - Every finding must include artifact path, record ID when available, severity, evidence, impact, and recommended next step. | ||
| - If a validation command exists in `validation-baseline.yaml`, prefer running or recommending that command; otherwise validate by inspection and targeted shell checks. | ||
| ## Four-Layer Validation Workflow | ||
| ### 1. Schema validity | ||
| Check: | ||
| - YAML parses cleanly. | ||
| - Every canonical artifact file being validated has matching shared schema coverage. | ||
| - Common envelope fields exist and are consistently shaped. | ||
| - Artifact-specific top-level keys match the matching schema. | ||
| - Required arrays/items are present, including newer required fields introduced by schema evolution. | ||
| - Stable IDs use expected prefixes for artifact family. | ||
| - Status, severity, confidence, and other constrained values match schemas. | ||
| - Required refs/evidence fields are present where schemas or workflow rules require them. | ||
| Use best-effort schema validation by inspection when no validator command exists. When a JSON Schema validator is available, run it against only relevant files and include command/results. | ||
| ### 2. Reference integrity | ||
| Build or inspect a canonical ID registry from artifacts read. Check: | ||
| - Every `*_ref`, `*_refs`, `depends_on`, `evidence_refs`, scope ref, contract ref, invariant ref, risk ref, issue ref, ADR ref, and artifact ref points to a known canonical ID or is explicitly external/unknown. | ||
| - Cross-scope refs have owner/consumer relationship support in `scopes.yaml` and, when API-like, `contracts.yaml`. | ||
| - Router/checklist artifacts reference owner facts instead of duplicating them. | ||
| - No record points to deleted, malformed, duplicate, or contradictory owner records. | ||
| Prefer compact missing-owner recommendations over leaving ambiguous dangling refs. | ||
| ### 3. Evidence validity | ||
| For evidence-bearing records, check: | ||
| - Referenced source paths exist under repo root when repo-aware validation is possible. | ||
| - Line ranges exist and are ordered when present. | ||
| - Referenced symbols/text are plausibly present near claimed paths or ranges. | ||
| - Evidence belongs to claimed scope and owner artifact. | ||
| - Observed records have evidence; planned records use explicit planned/low-confidence markers. | ||
| - `current`/high-confidence claims are not supported only by stale, missing, or unrelated evidence. | ||
| Do not claim semantic proof. Report stale/missing evidence as actionable quality risk. | ||
| ### 4. Coverage and granularity | ||
| Check: | ||
| - Changed files or high-value source areas have relevant scope or owner-artifact representation. | ||
| - Scope routing covers important paths without excessive overlap. | ||
| - Components/entities/contracts/risks are neither too broad to guide changes nor so tiny they fragment ownership. | ||
| - Repeated facts are owned once and referenced elsewhere. | ||
| - Validation/testing artifacts cover commands and risks important to the requested change. | ||
| Granularity is heuristic. Use warnings with concrete split/merge suggestions, not automatic failure, unless the docs cannot guide safe work. | ||
| ## Diff-Aware Mode | ||
| When user asks to validate after a diff: | ||
| 1. Inspect changed files with `git diff --name-only` or user-specified base. | ||
| 2. Match changed paths to scopes from `repo/scopes.yaml` when present. | ||
| 3. Read only relevant owner artifacts plus directly referenced artifacts. | ||
| 4. Prioritize evidence paths, owner refs, contracts, invariants, risks, tests, and validation baseline entries touched by the diff. | ||
| 5. Report undocumented changed files or stale evidence first. | ||
| ## Output Format | ||
| Use concise human output. Include machine-shaped summary when useful: | ||
| ```yaml | ||
| verdict: pass | pass_with_warnings | fail | blocked | ||
| schema: | ||
| status: pass | mixed | fail | blocked | ||
| findings: [] | ||
| refs: | ||
| status: pass | mixed | fail | blocked | ||
| findings: [] | ||
| evidence: | ||
| status: pass | mixed | fail | blocked | ||
| findings: [] | ||
| coverage: | ||
| status: pass | mixed | fail | blocked | ||
| findings: [] | ||
| granularity: | ||
| status: pass | mixed | fail | blocked | ||
| findings: [] | ||
| recommendations: [] | ||
| ``` | ||
| Finding shape: | ||
| ```yaml | ||
| severity: error | warning | info | ||
| artifact_path: <path> | ||
| record_id: <id-or-null> | ||
| layer: schema | refs | evidence | coverage | granularity | ||
| problem: <concise problem> | ||
| evidence: <file/path/command observation> | ||
| impact: <why it matters for agent workflows> | ||
| recommended_next_step: <specific repair or follow-up> | ||
| ``` | ||
| ## Verdict Rules | ||
| - `fail`: parse/schema errors, missing shared schema coverage for canonical artifacts, missing now-required fields, dangling required refs, missing required owner artifacts for selected scope, or missing evidence that makes current/high-confidence records unsafe. | ||
| - `pass_with_warnings`: schema/required refs are usable, but evidence, coverage, or granularity issues need follow-up. | ||
| - `pass`: no material issues found within inspected scope. | ||
| - `blocked`: docs root, required files, repo root, schemas, or commands cannot be accessed enough to validate. | ||
| ## Follow-Up Routing | ||
| - For broken artifact shape or invalid refs: recommend `safe-change` structured-docs-only repair or `codebase-recon` consolidation. | ||
| - For missing scope coverage: recommend `codebase-recon` on the relevant path/domain focus. | ||
| - For stale source evidence after code changes: recommend `safe-change` docs update for affected owner artifacts. | ||
| - For architecture/code concerns discovered while validating docs: recommend `arch-code-review`; do not turn validation output into code review findings unless requested. | ||
| ## Stop Conditions | ||
| Stop once the requested focus is validated enough to give a verdict and actionable findings. Do not exhaustively read a large repo when targeted evidence already proves the result. |
+14
-2
@@ -7,9 +7,21 @@ # Changelog | ||
| ## [0.6.0] - 2026-06-06 | ||
| ### Added | ||
| - None. | ||
| - Added stronger safe-start schema coverage for `project-intent`, `architecture`, `data-flow`, `data-model`, `risk-register`, `testing-strategy`, `contracts`, and `adr` artifacts so end-users and validators can catch missing greenfield architecture fields. | ||
| - Added pass-specific safe-start prompt guidance for prioritized quality attributes, trust boundaries, sensitive data, architecture tradeoffs, reliability, observability, security assumptions, quality-attribute verification, and thin-slice validation. | ||
| - Added parallel `codebase-recon` and `safe-change` prompt/reference guidance so reconstruction and change workflows also surface intent, quality attributes, trust boundaries, architecture rationale, risk actions, and schema blockers instead of relying on the older lighter artifact semantics. | ||
| - Added validation guidance that missing shared schema coverage or missing now-required fields in legacy artifacts should fail `/validate-structured-docs` audits. | ||
| ### Changed | ||
| - Upgraded `safe-start` workflow semantics so greenfield passes explicitly capture prioritized quality attributes, operating constraints, success metrics, trust boundaries, sensitive data handling, architecture alternatives/tradeoffs, reliability expectations, observability expectations, and security assumptions before scaffolding. | ||
| - Upgraded `codebase-recon` so inventory can seed `project-intent.yaml`, architecture/risk/testing passes align with the richer schemas, and consolidation can backfill missing now-required fields when evidence exists. | ||
| - Upgraded `safe-change` preflight/design/implementation guidance so changes explicitly account for documented quality attributes, operating constraints, trust boundaries, reliability/observability/security expectations, and schema blockers in older artifacts. | ||
| - Clarified README/tutorial/runtime docs that shared schemas are user-facing contracts and that validation should treat older artifacts missing newly required fields as invalid until repaired or migrated. | ||
| ### Fixes | ||
| - None. | ||
| - Clarified envelope `artifact_id` generation across write-capable structured-doc workflows so scoped artifact IDs use `<scope.id>/<artifact-slug>` instead of invalid second-colon form. | ||
@@ -16,0 +28,0 @@ ## [0.5.1] - 2026-05-25 |
+5
-3
| { | ||
| "name": "pi-agent-codebase-workflows", | ||
| "version": "0.5.1", | ||
| "description": "Pi skills and prompt templates for structured YAML artifact workflows: safe-start, codebase-recon, safe-change, architecture review, and legacy docs migration.", | ||
| "version": "0.6.0", | ||
| "description": "Pi skills and prompt templates for structured YAML artifact workflows: safe-start, codebase-recon, safe-change, architecture review, structured-doc validation, and legacy docs migration.", | ||
| "license": "MIT", | ||
@@ -17,3 +17,5 @@ "author": "PriNova", | ||
| "architecture", | ||
| "safe-change" | ||
| "safe-change", | ||
| "validation", | ||
| "structured-docs" | ||
| ], | ||
@@ -20,0 +22,0 @@ "homepage": "https://github.com/PriNova/pi-agent-codebase-workflows#readme", |
@@ -5,2 +5,12 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` bug diagnosis. Use canonical YAML artifacts only under the resolved structured docs root. Bug/focus: $ARGUMENTS. Diagnose violated invariant/contract/risk refs, root cause, minimal fix, regression test, validation command refs. Do not edit code. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` bug diagnosis. Use canonical YAML artifacts only under the resolved structured docs root. Bug/focus: $ARGUMENTS. | ||
| Diagnose: | ||
| - violated invariant/contract/risk refs | ||
| - impacted quality attributes or operating constraints | ||
| - root cause | ||
| - minimal fix | ||
| - regression test | ||
| - validation command refs | ||
| Do not edit code. |
@@ -5,2 +5,4 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` bug implementation. Follow approved plan. Use/update canonical YAML artifacts only under the resolved structured docs root when durable semantics changed. No legacy prose docs. Plan/focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` bug implementation. Follow approved plan. Use/update canonical YAML artifacts only under the resolved structured docs root when durable semantics changed. No legacy prose docs. | ||
| Keep the fix minimal, preserve documented quality/security/reliability expectations, add regression coverage, and fail fast if schema/doc blockers make the change unsafe to reason about. Plan/focus: $ARGUMENTS. |
@@ -5,2 +5,10 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` feature design. Use canonical YAML artifacts only under the resolved structured docs root. Feature/focus: $ARGUMENTS. Design flow/data/invariant/contract/component impacts, side effects, risks, tests, validation refs, and owner YAML updates. Do not edit code. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` feature design. Use canonical YAML artifacts only under the resolved structured docs root. Feature/focus: $ARGUMENTS. | ||
| Design: | ||
| - flow/data/invariant/contract/component impacts | ||
| - side effects and dependency changes | ||
| - impacted quality attributes, trust boundaries, security assumptions, reliability/observability expectations | ||
| - risks, tests, validation refs, and owner YAML updates | ||
| Do not edit code. |
@@ -5,2 +5,4 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` feature implementation. Follow approved design. Implement minimal change, add tests, validate, update owner YAML artifacts only for durable semantic changes. No legacy Markdown docs except root `AGENTS.md` when `agent-operating-guide.yaml` changes. Design/focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` feature implementation. Follow approved design. Implement minimal change, add tests, validate, update owner YAML artifacts only for durable semantic changes. No legacy Markdown docs except root `AGENTS.md` when `agent-operating-guide.yaml` changes. | ||
| Preserve or intentionally evolve documented quality/security/reliability expectations; if docs/schema gaps make that unclear, stop and repair docs first. Design/focus: $ARGUMENTS. |
+14
-1
@@ -5,2 +5,15 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` structured preflight. Read only canonical YAML artifacts under the resolved structured docs root; do not read legacy prose docs. Focus/task: $ARGUMENTS. Output classification, artifacts read, matched scope, affected files, invariant/contract/risk refs, validation command refs, and approval status. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` structured preflight. Read only canonical YAML artifacts under the resolved structured docs root; do not read legacy prose docs. | ||
| Output: | ||
| - classification | ||
| - artifacts read | ||
| - matched scope | ||
| - affected slice/module/user flow | ||
| - affected quality attributes / operating constraints when documented | ||
| - expected files | ||
| - invariant/contract/risk refs | ||
| - validation command refs | ||
| - approval or docs/schema-blocker status | ||
| If current docs omit now-required schema fields, treat that as a blocker or repair prerequisite rather than silently proceeding on partial truth. Focus/task: $ARGUMENTS. |
@@ -5,2 +5,12 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 1. Write/update `repo-inventory.yaml` and `validation-baseline.yaml`; update `scopes.yaml` when focused. Canonical YAML only under the resolved structured docs root. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 1. | ||
| Write/update `repo-inventory.yaml`, `validation-baseline.yaml`, and initial `project-intent.yaml`; update `scopes.yaml` when focused. | ||
| Infer from repo evidence when possible: | ||
| - product goal, target users, primary journeys, must-have features, non-goals | ||
| - prioritized quality attributes/nonfunctional priorities | ||
| - operating constraints, success metrics, and risk areas | ||
| - command/validation baseline and obvious blockers | ||
| If the codebase does not reveal some intent fields, keep the required fields present with low-confidence placeholders, explicit unknowns, and evidence explaining the ambiguity. Canonical YAML only under the resolved structured docs root. Focus: $ARGUMENTS. |
@@ -5,2 +5,10 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 2. Read structured inventory/validation YAML. Write/update `architecture.yaml` with components, style, boundaries, flow refs. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 2. Read structured inventory/validation YAML. | ||
| Write/update `architecture.yaml` with: | ||
| - components, style, boundaries, execution flow refs | ||
| - style rationale and plausible alternatives/tradeoffs when inferable | ||
| - reliability, observability, and security expectations seen in the codebase/docs/config | ||
| - deployment or operating shape when evident | ||
| If a required field is not inferable, keep it present and record the uncertainty explicitly rather than omitting it. YAML only. Focus: $ARGUMENTS. |
@@ -5,2 +5,12 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 3. Read structured inventory/architecture YAML. Write/update `data-model.yaml` and `invariants.yaml`. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 3. Read structured inventory/architecture YAML. | ||
| Write/update `data-model.yaml` and `invariants.yaml`. | ||
| Surface when observable from the repo: | ||
| - entity structure, lifecycles, serialized formats | ||
| - data classification, retention, and compliance notes | ||
| - invariants protecting correctness, security, or recovery behavior | ||
| - trust boundaries and sensitive-data handling implications that should be referenced by later flow/risk artifacts | ||
| YAML only. Focus: $ARGUMENTS. |
@@ -5,2 +5,6 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 4. Read structured inventory/architecture/data/invariant YAML. Write/update `dependency-rules.yaml` and `design-issues.yaml`. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 4. Read structured inventory/architecture/data/invariant YAML. | ||
| Write/update `dependency-rules.yaml` and `design-issues.yaml`. | ||
| Capture not only layering/import rules, but also structural ambiguity or missing evidence around quality attributes, operability, security boundaries, and ownership. YAML only. Focus: $ARGUMENTS. |
@@ -5,2 +5,13 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 5. Read structured architecture/data/invariants/dependency YAML. Write/update `risk-register.yaml`. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 5. Read structured architecture/data/invariants/dependency YAML. | ||
| Write/update `risk-register.yaml`. | ||
| Each risk should include at least: | ||
| - failure mode/title | ||
| - affected refs | ||
| - severity/confidence | ||
| - recommended action | ||
| - evidence refs | ||
| Prefer quality, security, reliability, and operability risks that are clearly evidenced by the repo over generic speculation. YAML only. Focus: $ARGUMENTS. |
@@ -5,2 +5,6 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 6. Write/update `agent-operating-guide.yaml` and root `AGENTS.md` for harness interoperability. Canonical facts remain in YAML; `AGENTS.md` stays compact and references canonical YAML. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 6. | ||
| Write/update `agent-operating-guide.yaml` and root `AGENTS.md` for harness interoperability. Canonical facts remain in YAML; `AGENTS.md` stays compact and references canonical YAML. | ||
| Include validation expectations and any operator/agent guardrails that matter for quality, security, reliability, or production safety. Focus: $ARGUMENTS. |
@@ -5,2 +5,2 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 7. Write/update `change-guide.yaml` with routing/checklists and owner artifact refs. YAML only; no Markdown. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 7. Write/update `change-guide.yaml` with routing/checklists and owner artifact refs. Include the change surfaces that matter most for quality attributes, contracts, risks, and validation. YAML only; no Markdown. Focus: $ARGUMENTS. |
@@ -5,2 +5,2 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 8. Consolidate canonical YAML artifacts under the resolved structured docs root, remove redundancy by owner refs, reconcile contradictions with evidence. Do not edit source or Markdown. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 8. Consolidate canonical YAML artifacts under the resolved structured docs root, remove redundancy by owner refs, reconcile contradictions with evidence, and backfill missing now-required fields in older artifacts when enough evidence exists. Do not edit source or Markdown. Focus: $ARGUMENTS. |
@@ -5,2 +5,2 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 9. Write/update `adr.yaml` structured ADR records with bounded prose fields. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 9. Write/update `adr.yaml` structured ADR records with bounded prose fields. Include alternatives and consequences when architectural decisions are inferable from code, docs, history, or surrounding evidence. YAML only. Focus: $ARGUMENTS. |
@@ -5,2 +5,12 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 10. Write/update `testing-strategy.yaml` with test topology, coverage gaps, and risk-to-test priorities. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` Pass 10. | ||
| Write/update `testing-strategy.yaml` with: | ||
| - `test_structure` | ||
| - `quality_attribute_coverage` | ||
| - `coverage_gaps` | ||
| - `risk_to_test_priorities` | ||
| - `known_blockers` | ||
| - `operability_checks` when relevant | ||
| Connect important risks and quality attributes to concrete validation expectations. YAML only. Focus: $ARGUMENTS. |
+10
-1
@@ -5,2 +5,11 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` all-in-one mode. Produce canonical YAML artifacts under the resolved structured docs root; root `AGENTS.md` may be generated in Pass 6 for harness interoperability. No other Markdown docs. Focus: $ARGUMENTS. If repo is too large, finish current pass and recommend next pass. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:codebase-recon` all-in-one mode. Produce canonical YAML artifacts under the resolved structured docs root; root `AGENTS.md` may be generated in Pass 6 for harness interoperability. No other Markdown docs. | ||
| Reconstruct not only inventory and structure, but also: | ||
| - project intent and likely quality attributes when inferable | ||
| - trust boundaries, sensitive data, retention/compliance notes | ||
| - architecture rationale/tradeoffs when evidence exists | ||
| - reliability, observability, and security expectations from code/config/docs | ||
| - risks, recommended actions, and test/operability coverage | ||
| If repo is too large, finish current pass and recommend next pass. Focus: $ARGUMENTS. |
@@ -5,2 +5,4 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` refactoring design. Use canonical YAML artifacts only. Identify design issue/dependency rule refs, behavior to preserve, characterization tests, staged plan, validation refs, rollback. Do not edit code. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` refactoring design. Use canonical YAML artifacts only. | ||
| Identify design issue/dependency rule refs, behavior and quality expectations to preserve, characterization tests, staged plan, validation refs, and rollback. Do not edit code. Focus: $ARGUMENTS. |
@@ -5,2 +5,4 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` refactoring implementation. Preserve behavior. Follow approved stage. Update owner YAML only when durable structure/rules changed. No legacy Markdown docs except root `AGENTS.md` when `agent-operating-guide.yaml` changes. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` refactoring implementation. Preserve behavior. Follow approved stage. Update owner YAML only when durable structure/rules changed. No legacy Markdown docs except root `AGENTS.md` when `agent-operating-guide.yaml` changes. | ||
| If the refactor would change documented quality or operating expectations, stop and reclassify as feature/design work first. Focus: $ARGUMENTS. |
@@ -5,2 +5,4 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` risk-fix workflow. Select one risk from `<docs-root>/**/risk-register.yaml` or a failing risk-derived test. Fix minimally, validate, update risk/testing YAML refs. No legacy prose docs. Risk/focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-change` risk-fix workflow. Select one risk from `<docs-root>/**/risk-register.yaml` or a failing risk-derived test. Fix minimally, validate, update risk/testing YAML refs. No legacy prose docs. | ||
| Explain invariant violated, impacted quality attribute or operating constraint, minimal fix, focused test, validation command refs, and updated risk status. Risk/focus: $ARGUMENTS. |
@@ -5,2 +5,25 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 1. Write/update `project-intent.yaml`, initial `repo-inventory.yaml`, optional `scopes.yaml`. YAML only. Input: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 1. | ||
| Write/update `project-intent.yaml`, initial `repo-inventory.yaml`, optional `scopes.yaml`. | ||
| Capture at minimum in `project-intent.yaml`: | ||
| - `intent.product_goal` | ||
| - `intent.target_users` | ||
| - `intent.primary_journeys` | ||
| - `intent.must_have_features` | ||
| - `intent.non_goals` | ||
| - `intent.constraints` | ||
| - `intent.assumptions` | ||
| - `intent.open_questions` | ||
| - `intent.quality_attributes` with priority and concrete scenario/target | ||
| - `intent.operating_constraints` | ||
| - `intent.success_metrics` | ||
| - `intent.risk_areas` | ||
| Pass-1 questions to force when unclear: | ||
| - What are the top 3 quality attributes or nonfunctional priorities? | ||
| - What deployment, privacy, compliance, latency, cost, or platform constraints shape architecture? | ||
| - What assumptions could invalidate later architecture work if wrong? | ||
| Ask one short clarification if product goal, target users, or top quality attributes are still unclear. Stop for approval after presenting the intent summary unless implementation was explicitly requested. YAML only. Input: $ARGUMENTS. |
@@ -5,2 +5,16 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 2. Write/update `data-flow.yaml`, `data-model.yaml`, and `invariants.yaml`. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 2. | ||
| Write/update `data-flow.yaml`, `data-model.yaml`, and `invariants.yaml`. | ||
| Capture at minimum: | ||
| - flows with `trigger`, `inputs`, ordered `steps`, `outputs`, `error_states`, `trust_boundaries`, `sensitive_data`, and `risk_refs` | ||
| - data entities/lifecycles/serialized formats plus retention/compliance notes when architecture-relevant | ||
| - invariants that protect correctness, security, or recovery behavior | ||
| Pass-2 questions to force when unclear: | ||
| - Where are trust boundaries, external actors, or privilege changes? | ||
| - What data is sensitive, regulated, durable, or recoverable? | ||
| - What can fail, what should degrade gracefully, and what must never silently fail? | ||
| Ask one short clarification if trust boundaries, sensitive data, or primary error states are still unclear. Stop for approval after presenting the data-flow summary unless implementation was explicitly requested. YAML only. Focus: $ARGUMENTS. |
@@ -5,2 +5,27 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 3. Write/update `architecture.yaml`, `dependency-rules.yaml`, `design-issues.yaml`, `risk-register.yaml`, and `adr.yaml`. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 3. | ||
| Write/update `architecture.yaml`, `dependency-rules.yaml`, `design-issues.yaml`, `risk-register.yaml`, and `adr.yaml`. | ||
| Capture at minimum in `architecture.yaml`: | ||
| - `architecture.style` | ||
| - `architecture.style_rationale` | ||
| - `architecture.alternatives_considered` | ||
| - `architecture.boundaries` | ||
| - `architecture.reliability_expectations` | ||
| - `architecture.observability_expectations` | ||
| - `architecture.security_assumptions` | ||
| - `components`, `dependency_direction`, `execution_flows`, `side_effect_boundaries` | ||
| Also ensure: | ||
| - major tradeoff decisions are reflected in `adr.yaml` | ||
| - unresolved ownership/quality gaps become `design-issues.yaml` records | ||
| - quality/security/reliability risks become `risk-register.yaml` records with recommended actions | ||
| Pass-3 questions to force when unclear: | ||
| - Why this architecture style over at least one plausible alternative? | ||
| - What must be observable from day 1: logs, metrics, traces, alerts, audit trails? | ||
| - How does the system handle retries, timeouts, degradation, recovery, backup, or failover? | ||
| - What auth, trust, or isolation assumptions exist between components? | ||
| Ask one short clarification if architecture style rationale, deployment shape, or observability/reliability expectations are still unclear. Stop for approval after presenting the architecture summary unless implementation was explicitly requested. YAML only. Focus: $ARGUMENTS. |
@@ -5,2 +5,16 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 4. Write/update structured YAML artifacts: `change-guide.yaml`, `testing-strategy.yaml`, `contracts.yaml` when needed, `agent-operating-guide.yaml`, and root `AGENTS.md` for harness interoperability. Do not write README or other prose docs. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 4. | ||
| Write/update structured YAML artifacts: `change-guide.yaml`, `testing-strategy.yaml`, `contracts.yaml` when the project has inter-process, persistence, deployment, env, auth, telemetry, or external integration boundaries, `agent-operating-guide.yaml`, and root `AGENTS.md` for harness interoperability. Do not write README or other prose docs. | ||
| Capture at minimum: | ||
| - `testing-strategy.yaml` with `test_structure`, `quality_attribute_coverage`, `coverage_gaps`, `risk_to_test_priorities`, `known_blockers`, and `operability_checks` when relevant | ||
| - `contracts.yaml` owner/consumer records for APIs, schemas, events, persistence, deployment, env, auth, telemetry, or CLI boundaries when they exist | ||
| - `agent-operating-guide.yaml` validation expectations and workflow guardrails for future agents | ||
| Pass-4 questions to force when unclear: | ||
| - What contracts exist across processes, scopes, environments, persistence boundaries, or external systems? | ||
| - What must be testable and operable from day 1 to trust the thin slice? | ||
| - Which quality attributes need explicit verification or operational checks? | ||
| If omitting `contracts.yaml` for a non-trivial project, record why in evidence/unknowns. Ask one short clarification if contract boundaries or quality-attribute verification strategy are still unclear. Continue without an extra approval gate unless unresolved contract or operability questions would materially change later passes. Focus: $ARGUMENTS. |
@@ -5,2 +5,12 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 5. Produce scaffold plan in chat only before file creation approval: tree, tooling, commands, generated files, risks. Do not create docs except canonical YAML updates already approved. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 5. | ||
| Produce scaffold plan in chat only before file creation approval: tree, tooling, commands, generated files, first thin slice, validation path, and major risks. Do not create docs except canonical YAML updates already approved. | ||
| The scaffold plan must: | ||
| - preserve the architecture boundaries and dependency rules already recorded | ||
| - identify how the first slice exercises a primary journey and at least one critical quality attribute or operating constraint | ||
| - include observability/security/reliability hooks needed for that first slice | ||
| - identify what to validate immediately after scaffolding | ||
| Ask one short clarification if the proposed scaffold cannot clearly satisfy the architecture constraints or first-slice validation path. Focus: $ARGUMENTS. |
@@ -5,2 +5,12 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 6. Run/record applicable validations and write/update `validation-baseline.yaml` with command status, blockers, recommended order. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 6. | ||
| Run/record applicable validations and write/update `validation-baseline.yaml` with command status, blockers, recommended order. | ||
| Validation baseline should cover when relevant: | ||
| - docs/schema validation for structured artifacts | ||
| - build/typecheck/lint/test commands | ||
| - smoke checks for the thin slice | ||
| - blockers caused by legacy artifacts or missing now-required schema fields | ||
| If structured docs predate current schemas, record missing required fields/schema failures as blockers rather than compatibility footnotes. YAML only. Focus: $ARGUMENTS. |
@@ -5,2 +5,11 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 7. Implement one thin vertical slice after approval/request. Update owner YAML artifacts only for durable semantic changes. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 7. | ||
| Implement one thin vertical slice after approval/request. The slice should exercise a primary user journey and at least one critical quality attribute or operating constraint when practical. Update owner YAML artifacts only for durable semantic changes. | ||
| Before implementation, confirm: | ||
| - which journey is being proven | ||
| - which quality attribute/constraint is being exercised | ||
| - which validation commands prove the slice is trustworthy | ||
| Ask one short clarification if the requested slice is too broad to validate cleanly or no meaningful validation path exists. Focus: $ARGUMENTS. |
@@ -5,2 +5,12 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 8. Verify structured artifacts are ready for `safe-change`; update `change-guide.yaml`, `risk-register.yaml`, `repo-inventory.yaml`, `design-issues.yaml`, and `scopes.yaml` as needed. YAML only. Focus: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` Pass 8. | ||
| Verify structured artifacts are ready for `safe-change`; update `change-guide.yaml`, `risk-register.yaml`, `repo-inventory.yaml`, `design-issues.yaml`, and `scopes.yaml` as needed. | ||
| Handoff must make unresolved work explicit: | ||
| - remaining quality-attribute gaps | ||
| - unresolved security/reliability/observability concerns | ||
| - missing contracts, tests, or validation commands | ||
| - recommended next workflow entrypoint for follow-up work | ||
| If the docs are not yet safe for `safe-change`, say so explicitly and record the blockers in owner artifacts rather than silently handing off. YAML only. Focus: $ARGUMENTS. |
@@ -5,2 +5,14 @@ --- | ||
| --- | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` all-in-one mode. Create canonical YAML artifacts under the resolved structured docs root and root `AGENTS.md` for harness interoperability. Do not create README or other prose docs as workflow artifacts. Stop for approval gates unless implementation explicitly requested. Input: $ARGUMENTS. | ||
| Before writing/updating structured artifacts, after loading the selected skill, load shared refs relative to that skill: `../_shared/references/artifact-api.md`, `../_shared/references/schemas/common.schema.json`, and only the matching artifact schema(s). Follow the skill Structured Artifact Write/Update Protocol for scope resolution, stable IDs, upserts, evidence, reference integrity, status transitions, deterministic YAML formatting, and validation. Resolve `<docs-root>` exactly per the selected skill: canonicalize `workspace_root`, use repo-local `<workspace_root>/docs/agent/api` only when that skill says repo-local applies and the directory exists, otherwise strip one leading slash/backslash from `workspace_root`, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Use `/skill:safe-start` all-in-one mode. | ||
| Create canonical YAML artifacts under the resolved structured docs root and root `AGENTS.md` for harness interoperability. Do not create README or other prose docs as workflow artifacts. | ||
| Run the pass sequence with these requirements: | ||
| - capture prioritized quality attributes, operating constraints, success metrics, and risk areas early | ||
| - surface trust boundaries, sensitive data, and failure/degradation behavior before architecture | ||
| - record architecture style rationale, alternatives, reliability expectations, observability expectations, and security assumptions | ||
| - write contracts when the project has API, persistence, deployment, env, auth, telemetry, or external-system boundaries | ||
| - build validation baseline that catches missing schema fields in legacy artifacts when structured docs already exist | ||
| - end with one thin vertical slice plus explicit handoff blockers/gaps | ||
| Stop for approval gates unless implementation was explicitly requested. Input: $ARGUMENTS. |
+15
-13
| # pi-agent-codebase-workflows | ||
| Pi package with agent-first skills and prompt templates for structured codebase understanding, safe greenfield starts, safe changes, architecture-aware review, and migration from deprecated prose docs. | ||
| Pi package with agent-first skills and prompt templates for structured codebase understanding, safe greenfield starts, safe changes, architecture-aware review, structured-doc validation, and migration from deprecated prose docs. | ||
@@ -30,6 +30,7 @@ ## Structured artifact model | ||
| - `safe-start` — create new projects with structured intent, data, architecture, contracts, validation, and handoff artifacts. | ||
| - `codebase-recon` — reconstruct existing codebases into structured YAML artifacts under the resolved structured docs root. | ||
| - `safe-change` — make documented-codebase changes using structured artifacts and update owner YAML only when durable semantics change. | ||
| - `safe-start` — create new projects with structured intent, prioritized quality attributes, data, architecture, contracts, validation, and handoff artifacts. | ||
| - `codebase-recon` — reconstruct existing codebases into structured YAML artifacts under the resolved structured docs root, including inferred intent/quality/risk context when evidence exists. | ||
| - `safe-change` — make documented-codebase changes using structured artifacts and update owner YAML only when durable semantics change, treating schema gaps in older artifacts as blockers or repair work when needed. | ||
| - `arch-code-review` — review diffs against structured architecture, data, invariant, dependency, risk, contract, and test artifacts from the resolved structured docs root. | ||
| - `structured-doc-validate` — validate structured YAML docs for schema shape, shared schema coverage, reference integrity, evidence quality, coverage, and granularity. | ||
| - `structured-docs-migration` — migrate deprecated prose-style docs into canonical structured YAML artifacts under the resolved structured docs root. | ||
@@ -65,3 +66,3 @@ | ||
| Safe change / review / migration: | ||
| Safe change / review / validation / migration: | ||
@@ -77,2 +78,3 @@ - `/preflight` | ||
| - `/review-arch` | ||
| - `/validate-structured-docs` | ||
| - `/migrate-structured-docs` | ||
@@ -123,12 +125,12 @@ | ||
| - `validation-baseline.yaml`: command status, blockers, validation order. | ||
| - `project-intent.yaml`: goals, users, journeys, constraints. | ||
| - `architecture.yaml`: components, style, side-effect boundaries. | ||
| - `data-flow.yaml`: typed flow graph and error states. | ||
| - `data-model.yaml`: entities, IDs, schemas, lifecycles, serialized formats. | ||
| - `project-intent.yaml`: goals, users, journeys, constraints, prioritized quality attributes, operating constraints. | ||
| - `architecture.yaml`: components, style, style rationale, alternatives, side-effect boundaries, reliability/observability/security expectations. | ||
| - `data-flow.yaml`: typed flow graph, trust boundaries, sensitive-data handling, error states. | ||
| - `data-model.yaml`: entities, IDs, schemas, lifecycles, serialized formats, retention/compliance notes. | ||
| - `invariants.yaml`: rules, forbidden states, enforcement. | ||
| - `dependency-rules.yaml`: layers, allowed/forbidden dependencies, violations. | ||
| - `design-issues.yaml`: drift, deferred decisions, ownership gaps. | ||
| - `risk-register.yaml`: failure modes and suggested tests/fixes. | ||
| - `contracts.yaml`: APIs, schemas, events, generated clients, persistence/deployment/env contracts. | ||
| - `testing-strategy.yaml`: test topology, gaps, risk-to-test priorities. | ||
| - `risk-register.yaml`: failure modes, affected refs, recommended actions, and suggested tests/fixes. | ||
| - `contracts.yaml`: APIs, schemas, events, generated clients, persistence/deployment/env/auth/telemetry contracts. | ||
| - `testing-strategy.yaml`: test topology, quality-attribute coverage, gaps, risk-to-test priorities. | ||
| - `change-guide.yaml`: workflow routing and checklists. | ||
@@ -144,3 +146,3 @@ - `adr.yaml`: structured ADR records. | ||
| Validation is best-effort by agent inspection and re-read. | ||
| Validation is best-effort by agent inspection and re-read. The `structured-doc-validate` skill gives a read-only four-layer audit workflow for schema validity, shared schema coverage, references, evidence, coverage, and granularity. Shared schemas are user-facing contracts too, so older artifacts missing newly required fields should fail validation until repaired or migrated. | ||
@@ -147,0 +149,0 @@ ## Package structure |
@@ -49,4 +49,14 @@ # Structured Artifact API Runtime Reference | ||
| ## Envelope artifact IDs | ||
| - Repo-level artifact IDs use `repo:<artifact-slug>`, e.g. `repo:architecture`. | ||
| - Scoped artifact IDs append the artifact slug to the scope ID with `/`, e.g. `scope:packages/ai/architecture`. | ||
| - Never append an artifact slug to a scope ID with a second colon. `scope:packages/ai:architecture` is invalid because stable IDs allow only the prefix colon. | ||
| ## Runtime rule | ||
| Schemas are contracts. Skills/prompts describe behavior. Project docs outside these shared runtime refs are maintainer aids and are not runtime instructions unless user explicitly asks about this package itself. | ||
| ## Schema evolution note | ||
| Shared schemas are user-facing contracts too. When new required fields are introduced, older artifacts that omit them are invalid until repaired or migrated. Validation should report missing schema coverage or missing now-required fields as schema failures, not as compatibility footnotes. |
@@ -34,3 +34,8 @@ { | ||
| "required": [ | ||
| "id" | ||
| "id", | ||
| "title", | ||
| "status", | ||
| "context", | ||
| "decision", | ||
| "consequences" | ||
| ], | ||
@@ -41,2 +46,26 @@ "properties": { | ||
| "pattern": "^adr:[a-z0-9][a-z0-9._/-]*$" | ||
| }, | ||
| "title": { | ||
| "type": "string" | ||
| }, | ||
| "status": { | ||
| "type": "string" | ||
| }, | ||
| "context": { | ||
| "type": "string" | ||
| }, | ||
| "decision": { | ||
| "type": "string" | ||
| }, | ||
| "consequences": { | ||
| "type": "array" | ||
| }, | ||
| "alternatives": { | ||
| "type": "array" | ||
| }, | ||
| "related_refs": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| } | ||
| } | ||
@@ -43,0 +72,0 @@ }, |
@@ -34,3 +34,120 @@ { | ||
| "architecture": { | ||
| "type": "object" | ||
| "type": "object", | ||
| "required": [ | ||
| "style", | ||
| "style_rationale", | ||
| "alternatives_considered", | ||
| "boundaries", | ||
| "reliability_expectations", | ||
| "observability_expectations", | ||
| "security_assumptions" | ||
| ], | ||
| "properties": { | ||
| "style": { | ||
| "type": "string" | ||
| }, | ||
| "style_rationale": { | ||
| "type": "string" | ||
| }, | ||
| "alternatives_considered": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "boundaries": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "reliability_expectations": { | ||
| "type": "object", | ||
| "properties": { | ||
| "availability_target": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "degradation_strategy": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "recovery_strategy": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "backup_or_failover": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| } | ||
| }, | ||
| "additionalProperties": true | ||
| }, | ||
| "observability_expectations": { | ||
| "type": "object", | ||
| "properties": { | ||
| "logs": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "metrics": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "traces": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "alerts": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| } | ||
| }, | ||
| "additionalProperties": true | ||
| }, | ||
| "security_assumptions": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "deployment_shape": { | ||
| "type": [ | ||
| "object", | ||
| "null" | ||
| ] | ||
| }, | ||
| "operating_model": { | ||
| "type": [ | ||
| "object", | ||
| "null" | ||
| ] | ||
| } | ||
| }, | ||
| "additionalProperties": true | ||
| }, | ||
@@ -37,0 +154,0 @@ "components": { |
@@ -34,3 +34,7 @@ { | ||
| "required": [ | ||
| "id" | ||
| "id", | ||
| "kind", | ||
| "summary", | ||
| "owner", | ||
| "consumers" | ||
| ], | ||
@@ -41,2 +45,41 @@ "properties": { | ||
| "pattern": "^contract:[a-z0-9][a-z0-9._/-]*$" | ||
| }, | ||
| "kind": { | ||
| "type": "string" | ||
| }, | ||
| "summary": { | ||
| "type": "string" | ||
| }, | ||
| "owner": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| }, | ||
| "consumers": { | ||
| "type": "array" | ||
| }, | ||
| "compatibility": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "failure_semantics": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "security_notes": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "observability_notes": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| } | ||
@@ -43,0 +86,0 @@ }, |
@@ -34,3 +34,11 @@ { | ||
| "required": [ | ||
| "id" | ||
| "id", | ||
| "trigger", | ||
| "inputs", | ||
| "steps", | ||
| "outputs", | ||
| "error_states", | ||
| "trust_boundaries", | ||
| "sensitive_data", | ||
| "risk_refs" | ||
| ], | ||
@@ -41,2 +49,45 @@ "properties": { | ||
| "pattern": "^flow:[a-z0-9][a-z0-9._/-]*$" | ||
| }, | ||
| "trigger": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| }, | ||
| "inputs": { | ||
| "type": "array" | ||
| }, | ||
| "steps": { | ||
| "type": "array" | ||
| }, | ||
| "outputs": { | ||
| "type": "array" | ||
| }, | ||
| "error_states": { | ||
| "type": "array" | ||
| }, | ||
| "trust_boundaries": { | ||
| "type": "array" | ||
| }, | ||
| "sensitive_data": { | ||
| "type": "array" | ||
| }, | ||
| "risk_refs": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string", | ||
| "pattern": "^risk:[a-z0-9][a-z0-9._/-]*$" | ||
| } | ||
| }, | ||
| "degradation_notes": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "recovery_notes": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| } | ||
@@ -43,0 +94,0 @@ }, |
@@ -42,2 +42,14 @@ { | ||
| "pattern": "^entity:[a-z0-9][a-z0-9._/-]*$" | ||
| }, | ||
| "data_classification": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "retention_class": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| } | ||
@@ -53,4 +65,10 @@ }, | ||
| "type": "array" | ||
| }, | ||
| "retention_notes": { | ||
| "type": "array" | ||
| }, | ||
| "compliance_notes": { | ||
| "type": "array" | ||
| } | ||
| } | ||
| } |
@@ -30,3 +30,152 @@ { | ||
| "intent": { | ||
| "type": "object" | ||
| "type": "object", | ||
| "required": [ | ||
| "product_goal", | ||
| "target_users", | ||
| "primary_journeys", | ||
| "must_have_features", | ||
| "non_goals", | ||
| "constraints", | ||
| "assumptions", | ||
| "open_questions", | ||
| "quality_attributes", | ||
| "operating_constraints", | ||
| "success_metrics", | ||
| "risk_areas" | ||
| ], | ||
| "properties": { | ||
| "product_goal": { | ||
| "type": "string" | ||
| }, | ||
| "target_users": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "primary_journeys": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "must_have_features": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "non_goals": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "constraints": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "assumptions": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "open_questions": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "quality_attributes": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "object", | ||
| "required": [ | ||
| "name", | ||
| "priority", | ||
| "scenario" | ||
| ], | ||
| "properties": { | ||
| "name": { | ||
| "type": "string" | ||
| }, | ||
| "priority": { | ||
| "enum": [ | ||
| "high", | ||
| "medium", | ||
| "low" | ||
| ] | ||
| }, | ||
| "scenario": { | ||
| "type": "string" | ||
| }, | ||
| "target": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "tradeoff_notes": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| } | ||
| }, | ||
| "additionalProperties": true | ||
| } | ||
| }, | ||
| "operating_constraints": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "success_metrics": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| }, | ||
| "risk_areas": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": [ | ||
| "string", | ||
| "object" | ||
| ] | ||
| } | ||
| } | ||
| }, | ||
| "additionalProperties": true | ||
| }, | ||
@@ -33,0 +182,0 @@ "goals": { |
@@ -39,3 +39,5 @@ { | ||
| "status", | ||
| "evidence_refs" | ||
| "evidence_refs", | ||
| "affected_refs", | ||
| "recommended_action" | ||
| ], | ||
@@ -74,2 +76,23 @@ "properties": { | ||
| } | ||
| }, | ||
| "affected_refs": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| } | ||
| }, | ||
| "recommended_action": { | ||
| "type": "string" | ||
| }, | ||
| "mitigation_refs": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| } | ||
| }, | ||
| "test_refs": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| } | ||
| } | ||
@@ -76,0 +99,0 @@ }, |
@@ -24,2 +24,3 @@ { | ||
| "test_structure", | ||
| "quality_attribute_coverage", | ||
| "coverage_gaps", | ||
@@ -36,2 +37,5 @@ "risk_to_test_priorities", | ||
| }, | ||
| "quality_attribute_coverage": { | ||
| "type": "array" | ||
| }, | ||
| "coverage_gaps": { | ||
@@ -46,2 +50,5 @@ "type": "array" | ||
| }, | ||
| "operability_checks": { | ||
| "type": "array" | ||
| }, | ||
| "test_plans": { | ||
@@ -58,2 +65,17 @@ "type": "array", | ||
| "pattern": "^testplan:[a-z0-9][a-z0-9._/-]*$" | ||
| }, | ||
| "objective": { | ||
| "type": "string" | ||
| }, | ||
| "layer": { | ||
| "type": [ | ||
| "string", | ||
| "null" | ||
| ] | ||
| }, | ||
| "related_refs": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| } | ||
| } | ||
@@ -60,0 +82,0 @@ }, |
@@ -62,14 +62,14 @@ --- | ||
| - `validation-baseline`: command status, blockers, recommended validation order. | ||
| - `project-intent`: goals, users, journeys, non-goals, constraints, assumptions. | ||
| - `architecture`: components, architecture style, side-effect boundaries, high-level flow refs. | ||
| - `data-flow`: typed flow graph/steps, inputs, outputs, error states. | ||
| - `data-model`: entities, IDs, schemas, relationships, lifecycles, serialized formats. | ||
| - `project-intent`: product goal, users, journeys, must-have features, non-goals, constraints, assumptions, open questions, success metrics, prioritized quality attributes, operating constraints, risk areas. | ||
| - `architecture`: components, architecture style, style rationale, alternatives/tradeoffs, side-effect boundaries, deployment/operating shape, reliability expectations, observability expectations, security assumptions, high-level flow refs. | ||
| - `data-flow`: typed flow graph/steps, trust boundaries, sensitive-data handling steps, inputs, outputs, error states, degradation/recovery notes. | ||
| - `data-model`: entities, IDs, schemas, relationships, lifecycles, serialized formats, retention/compliance notes. | ||
| - `invariants`: rules, forbidden states, enforcement locations, invariant-test refs. | ||
| - `dependency-rules`: layers, allowed/forbidden dependencies, violations, coupling hotspots. | ||
| - `design-issues`: structural drift, deferred decisions, ambiguity, ownership gaps. | ||
| - `risk-register`: failure modes, severity/confidence, affected refs, suggested tests/fixes. | ||
| - `contracts`: cross-scope APIs, schemas, events, generated clients, DB/file/deployment/env contracts. | ||
| - `testing-strategy`: test topology, coverage gaps, risk-to-test priorities. | ||
| - `risk-register`: failure modes, severity/confidence, affected refs, mitigations/recommended actions, suggested tests/fixes. | ||
| - `contracts`: cross-scope APIs, schemas, events, generated clients, DB/file/deployment/env/auth/telemetry contracts. | ||
| - `testing-strategy`: test topology, quality-attribute coverage, coverage gaps, risk-to-test priorities, operability checks. | ||
| - `change-guide`: workflow routing and checklists; references owner artifacts, duplicates no facts. | ||
| - `adr`: structured decision records with bounded prose fields. | ||
| - `adr`: structured decision records with bounded prose fields, including alternatives and consequences for major design choices. | ||
| - `agent-operating-guide`: structured source for agent operating rules. Root `AGENTS.md` may mirror this in compact harness-readable Markdown when produced by safe-start or codebase-recon Pass 6. | ||
@@ -113,5 +113,7 @@ | ||
| 1. Reuse existing IDs whenever the semantic object is the same, even if name/path changed. | ||
| 2. New IDs use deterministic slugs from owner scope + semantic name: `risk:<slug>`, `entity:<slug>`, `component:<slug>`, etc. | ||
| 3. If two objects slug-collide, append shortest stable discriminator from path/component/contract, not a random suffix. | ||
| 4. Never renumber IDs because order changed. | ||
| 2. New record IDs use deterministic slugs from owner scope + semantic name: `risk:<slug>`, `entity:<slug>`, `component:<slug>`, etc. | ||
| 3. Envelope `artifact_id` values use `repo:<artifact-slug>` for repo-level artifacts and `<scope.id>/<artifact-slug>` for scoped artifacts, e.g. `repo:architecture` and `scope:packages/ai/architecture`. | ||
| 4. Never append an artifact slug to a scope ID with a second colon; `scope:packages/ai:architecture` is invalid. | ||
| 5. If two objects slug-collide, append shortest stable discriminator from path/component/contract, not a random suffix. | ||
| 6. Never renumber IDs because order changed. | ||
@@ -182,2 +184,4 @@ ### 4. Upsert semantics | ||
| - Unknowns are explicit records, not vague prose. | ||
| - When newer schemas require fields that are not inferable from the codebase, still create those fields with evidence-backed low-confidence placeholders, empty arrays, null-capable subfields, and explicit unknowns rather than omitting them. | ||
| - Reconstruct decision-driving quality attributes, trust boundaries, reliability/observability/security expectations, and tradeoffs when the repo provides enough evidence; otherwise record the ambiguity explicitly. | ||
| - Use stable IDs and cross-references to mirror codebase ownership and relationships. | ||
@@ -189,12 +193,12 @@ | ||
| 1. Inventory (`/recon-01-inventory`): write `repo-inventory.yaml` and `validation-baseline.yaml`; update `scopes.yaml` for focus. | ||
| 2. Architecture (`/recon-02-architecture`): write `architecture.yaml` with components, style, boundaries, execution flow refs. | ||
| 3. Data/invariants (`/recon-03-data-invariants`): write `data-model.yaml` and `invariants.yaml`. | ||
| 4. Dependencies/drift (`/recon-04-dependency-rules`): write `dependency-rules.yaml` and `design-issues.yaml`. | ||
| 5. Risks (`/recon-05-risk-register`): write `risk-register.yaml`. | ||
| 1. Inventory (`/recon-01-inventory`): write `repo-inventory.yaml`, `validation-baseline.yaml`, and initial `project-intent.yaml`; update `scopes.yaml` for focus. Infer product goal, users, journeys, quality attributes, operating constraints, and risk areas from repo evidence when possible; otherwise record explicit unknowns. | ||
| 2. Architecture (`/recon-02-architecture`): write `architecture.yaml` with components, style, style rationale, alternatives/tradeoffs when inferable, boundaries, execution flow refs, and reliability/observability/security expectations. | ||
| 3. Data/invariants (`/recon-03-data-invariants`): write `data-model.yaml` and `invariants.yaml`; surface trust boundaries, sensitive data, retention/compliance implications, and correctness/safety rules. | ||
| 4. Dependencies/drift (`/recon-04-dependency-rules`): write `dependency-rules.yaml` and `design-issues.yaml`; record structural gaps where quality/security/operability evidence is weak. | ||
| 5. Risks (`/recon-05-risk-register`): write `risk-register.yaml` with affected refs, recommended actions, and quality/security/reliability risks. | ||
| 6. Agent operating guide (`/recon-06-agents`): write `agent-operating-guide.yaml` and root `AGENTS.md`. | ||
| 7. Change guide (`/recon-07-change-guide`): write `change-guide.yaml`. | ||
| 8. Consolidation (`/recon-08-consolidate`): reconcile YAML artifacts, resolve contradictions with evidence, preserve owner-only facts. | ||
| 9. ADR (`/recon-09-adr`): write `adr.yaml` with structured ADR records. | ||
| 10. Risk-to-tests (`/recon-10-risk-tests`): write/update `testing-strategy.yaml`. | ||
| 8. Consolidation (`/recon-08-consolidate`): reconcile YAML artifacts, resolve contradictions with evidence, preserve owner-only facts, and backfill required schema fields when older artifacts are incomplete. | ||
| 9. ADR (`/recon-09-adr`): write `adr.yaml` with structured ADR records, alternatives, and consequences where architectural decisions are inferable from history/docs/code. | ||
| 10. Risk-to-tests (`/recon-10-risk-tests`): write/update `testing-strategy.yaml` with quality-attribute coverage, risk-to-test priorities, and operability checks. | ||
@@ -201,0 +205,0 @@ All-in-one shortcut: `/recon-all` runs the pass sequence until the requested focus is complete or the repo size requires stopping at a pass boundary. |
| # Structured Bug Fix | ||
| Diagnose before edits using structured YAML artifacts only. Identify violated invariant/contract/risk refs, root cause, minimal fix, regression test plan, and validation command refs. Implement only after approval unless explicitly requested. Update `risk-register.yaml`, `invariants.yaml`, `data-model.yaml`, or `contracts.yaml` only for durable semantic changes. | ||
| Diagnose before edits using structured YAML artifacts only. Identify violated invariant/contract/risk refs, impacted quality attributes or operating constraints, root cause, minimal fix, regression test plan, and validation command refs. Implement only after approval unless explicitly requested. Update `risk-register.yaml`, `invariants.yaml`, `data-model.yaml`, `data-flow.yaml`, or `contracts.yaml` only for durable semantic changes. |
| # Structured Artifact Update Rules | ||
| Update only canonical YAML owner artifacts under the resolved structured docs root. Treat them as current truth, not audit history. Resolve `<docs-root>` exactly: use repo-local `<workspace_root>/docs/agent/api` only when it already exists; otherwise canonicalize `workspace_root`, strip one leading slash/backslash, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Remove resolved or superseded records by default; keep `stale`/`deprecated` records only when live references or active migrations require temporary continuity. Do not create/update Markdown except root `AGENTS.md` when `agent-operating-guide.yaml` changes and harness interoperability guidance must mirror it. Owner mapping: scopes, repo-inventory, validation-baseline, project-intent, architecture, data-flow, data-model, invariants, dependency-rules, design-issues, risk-register, contracts, testing-strategy, change-guide, adr, agent-operating-guide. Use the skill Structured Artifact Write/Update Protocol: read before write, preserve stable IDs, upsert by ID/source-of-truth fields, prune unreferenced resolved/superseded records, require evidence, validate refs, use deterministic YAML formatting, and report validation. | ||
| Update only canonical YAML owner artifacts under the resolved structured docs root. Treat them as current truth, not audit history. Resolve `<docs-root>` exactly: use repo-local `<workspace_root>/docs/agent/api` only when it already exists; otherwise canonicalize `workspace_root`, strip one leading slash/backslash, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Remove resolved or superseded records by default; keep `stale`/`deprecated` records only when live references or active migrations require temporary continuity. Do not create/update Markdown except root `AGENTS.md` when `agent-operating-guide.yaml` changes and harness interoperability guidance must mirror it. Owner mapping: scopes, repo-inventory, validation-baseline, project-intent, architecture, data-flow, data-model, invariants, dependency-rules, design-issues, risk-register, contracts, testing-strategy, change-guide, adr, agent-operating-guide. Use the skill Structured Artifact Write/Update Protocol: read before write, preserve stable IDs, upsert by ID/source-of-truth fields, prune unreferenced resolved/superseded records, require evidence, validate refs, use deterministic YAML formatting, and report validation. Treat missing now-required schema fields in older artifacts as repair work, not as optional omissions. |
| # Structured Feature | ||
| Design before edits. Identify flow/data/invariant/contract/component impacts, side-effect boundaries, risks, test plan, validation command refs, and owner YAML artifacts to update. Implement after approval unless explicitly requested. | ||
| Design before edits. Identify flow/data/invariant/contract/component impacts, side-effect boundaries, quality/security/reliability implications, risks, test plan, validation command refs, and owner YAML artifacts to update. Implement after approval unless explicitly requested. |
| # Structured Preflight | ||
| Read `<docs-root>/repo/scopes.yaml` if present, match scope, then read only relevant owner YAML artifacts under the resolved structured docs root. Do not read legacy prose docs. Resolve `<docs-root>` exactly: use repo-local `<workspace_root>/docs/agent/api` only when it already exists; otherwise canonicalize `workspace_root`, strip one leading slash/backslash, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Produce classification, artifacts read, scope, affected files, invariant/contract/risk refs, validation command refs, and approval status. | ||
| Read `<docs-root>/repo/scopes.yaml` if present, match scope, then read only relevant owner YAML artifacts under the resolved structured docs root. Do not read legacy prose docs. Resolve `<docs-root>` exactly: use repo-local `<workspace_root>/docs/agent/api` only when it already exists; otherwise canonicalize `workspace_root`, strip one leading slash/backslash, replace every slash, backslash, and colon with `-`, wrap with `--`, and use `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. Produce classification, artifacts read, scope, affected files, affected quality attributes or operating constraints when documented, invariant/contract/risk refs, validation command refs, and approval/docs-schema-blocker status. If current artifacts omit now-required schema fields, treat that as a repair prerequisite or explicit blocker. |
| # Structured Refactoring | ||
| Behavior-preserving only. Identify `design-issues.yaml` issue refs, `dependency-rules.yaml` rule refs, behavior to preserve, characterization tests, staged plan, validation command refs, rollback. Update owner YAML only when durable structure/rules changed. | ||
| Behavior-preserving only. Identify `design-issues.yaml` issue refs, `dependency-rules.yaml` rule refs, behavior and documented quality expectations to preserve, characterization tests, staged plan, validation command refs, rollback. Update owner YAML only when durable structure/rules changed. |
| # Structured Risk Fix | ||
| Use structured YAML artifacts only. Select one `risk-register.yaml` risk or tightly related cluster. Explain invariant violated, minimal fix, focused test, validation command refs. Update risk status and testing strategy refs after validation. | ||
| Use structured YAML artifacts only. Select one `risk-register.yaml` risk or tightly related cluster. Explain invariant violated, impacted quality attribute or operating constraint, minimal fix, focused test, validation command refs. Update risk status and testing strategy refs after validation. |
@@ -62,14 +62,14 @@ --- | ||
| - `validation-baseline`: command status, blockers, recommended validation order. | ||
| - `project-intent`: goals, users, journeys, non-goals, constraints, assumptions. | ||
| - `architecture`: components, architecture style, side-effect boundaries, high-level flow refs. | ||
| - `data-flow`: typed flow graph/steps, inputs, outputs, error states. | ||
| - `data-model`: entities, IDs, schemas, relationships, lifecycles, serialized formats. | ||
| - `project-intent`: product goal, users, journeys, must-have features, non-goals, constraints, assumptions, open questions, success metrics, prioritized quality attributes, operating constraints, risk areas. | ||
| - `architecture`: components, architecture style, style rationale, alternatives/tradeoffs, side-effect boundaries, deployment/operating shape, reliability expectations, observability expectations, security assumptions, high-level flow refs. | ||
| - `data-flow`: typed flow graph/steps, trust boundaries, sensitive-data handling steps, inputs, outputs, error states, degradation/recovery notes. | ||
| - `data-model`: entities, IDs, schemas, relationships, lifecycles, serialized formats, retention/compliance notes. | ||
| - `invariants`: rules, forbidden states, enforcement locations, invariant-test refs. | ||
| - `dependency-rules`: layers, allowed/forbidden dependencies, violations, coupling hotspots. | ||
| - `design-issues`: structural drift, deferred decisions, ambiguity, ownership gaps. | ||
| - `risk-register`: failure modes, severity/confidence, affected refs, suggested tests/fixes. | ||
| - `contracts`: cross-scope APIs, schemas, events, generated clients, DB/file/deployment/env contracts. | ||
| - `testing-strategy`: test topology, coverage gaps, risk-to-test priorities. | ||
| - `risk-register`: failure modes, severity/confidence, affected refs, mitigations/recommended actions, suggested tests/fixes. | ||
| - `contracts`: cross-scope APIs, schemas, events, generated clients, DB/file/deployment/env/auth/telemetry contracts. | ||
| - `testing-strategy`: test topology, quality-attribute coverage, coverage gaps, risk-to-test priorities, operability checks. | ||
| - `change-guide`: workflow routing and checklists; references owner artifacts, duplicates no facts. | ||
| - `adr`: structured decision records with bounded prose fields. | ||
| - `adr`: structured decision records with bounded prose fields, including alternatives and consequences for major design choices. | ||
| - `agent-operating-guide`: structured source for agent operating rules. Root `AGENTS.md` may mirror this in compact harness-readable Markdown when produced by safe-start or codebase-recon Pass 6. | ||
@@ -113,5 +113,7 @@ | ||
| 1. Reuse existing IDs whenever the semantic object is the same, even if name/path changed. | ||
| 2. New IDs use deterministic slugs from owner scope + semantic name: `risk:<slug>`, `entity:<slug>`, `component:<slug>`, etc. | ||
| 3. If two objects slug-collide, append shortest stable discriminator from path/component/contract, not a random suffix. | ||
| 4. Never renumber IDs because order changed. | ||
| 2. New record IDs use deterministic slugs from owner scope + semantic name: `risk:<slug>`, `entity:<slug>`, `component:<slug>`, etc. | ||
| 3. Envelope `artifact_id` values use `repo:<artifact-slug>` for repo-level artifacts and `<scope.id>/<artifact-slug>` for scoped artifacts, e.g. `repo:architecture` and `scope:packages/ai/architecture`. | ||
| 4. Never append an artifact slug to a scope ID with a second colon; `scope:packages/ai:architecture` is invalid. | ||
| 5. If two objects slug-collide, append shortest stable discriminator from path/component/contract, not a random suffix. | ||
| 6. Never renumber IDs because order changed. | ||
@@ -182,2 +184,4 @@ ### 4. Upsert semantics | ||
| - Add tests for risky or uncovered behavior. | ||
| - Treat prioritized quality attributes, operating constraints, trust boundaries, reliability expectations, observability expectations, and security assumptions as first-class change constraints when those owner artifacts contain them. | ||
| - If current structured artifacts predate newer schemas and omit now-required fields, surface that as a docs/schema blocker and route through structured-docs repair when needed instead of silently proceeding on incomplete truth. | ||
| - Update structured artifacts only when durable semantics changed. | ||
@@ -206,6 +210,7 @@ | ||
| 4. affected slice/module/user flow | ||
| 5. expected files to inspect | ||
| 6. invariant/contract/risk refs at stake | ||
| 7. validation command refs | ||
| 8. proceed or wait for approval | ||
| 5. affected quality attributes / operating constraints when documented | ||
| 6. expected files to inspect | ||
| 7. invariant/contract/risk refs at stake | ||
| 8. validation command refs | ||
| 9. proceed, wait for approval, or repair docs/schema blockers first | ||
@@ -217,9 +222,9 @@ ## Workflow Selection | ||
| - Preflight (`/preflight`): classify task, match scope, identify owner artifacts/refs, and decide proceed vs approval. | ||
| - Bug diagnosis (`/bug-diagnose`): diagnose expected behavior, violated invariant/contract, root cause, minimal fix, regression test. | ||
| - Bug diagnosis (`/bug-diagnose`): diagnose expected behavior, violated invariant/contract/risk, impacted quality attributes or operating constraints, root cause, minimal fix, regression test. | ||
| - Bug implementation (`/bug-implement`): implement approved minimal fix, add regression test, validate, update durable YAML facts only when semantics changed. | ||
| - Feature design (`/feature-design`): design flow/data/invariant/contract impacts, side effects, risks, tests, docs updates. | ||
| - Feature design (`/feature-design`): design flow/data/invariant/contract/component impacts, side effects, quality/security/reliability implications, tests, docs updates. | ||
| - Feature implementation (`/feature-implement`): implement approved design minimally, test, validate, update owner YAML artifacts when durable semantics changed. | ||
| - Refactor design (`/refactor-design`): preserve behavior, identify design issue/dependency rule, characterization tests, staged plan. | ||
| - Refactor design (`/refactor-design`): preserve behavior and documented quality expectations, identify design issue/dependency rule, characterization tests, staged plan. | ||
| - Refactor implementation (`/refactor-implement`): execute approved refactor stage, keep behavior stable, validate. | ||
| - Risk fix (`/risk-fix`): select one risk or failing risk-derived test, fix minimally, update risk status. | ||
| - Risk fix (`/risk-fix`): select one risk or failing risk-derived test, fix minimally, update risk status and related verification refs. | ||
| - Test-only: preserve behavior; update testing strategy only if durable coverage/risk facts changed. | ||
@@ -231,14 +236,14 @@ - Structured-docs-only: update owner YAML artifacts only. | ||
| Update owners only: | ||
| - intent/scope/non-goals -> `project-intent.yaml` | ||
| - intent/scope/non-goals/quality attributes/operating constraints -> `project-intent.yaml` | ||
| - file tree/entry points/command index -> `repo-inventory.yaml` | ||
| - command status/blockers -> `validation-baseline.yaml` | ||
| - architecture/components/boundaries -> `architecture.yaml` | ||
| - flows/error states -> `data-flow.yaml` | ||
| - schemas/entities/lifecycles -> `data-model.yaml` | ||
| - architecture/components/boundaries/style rationale/reliability-observability-security expectations -> `architecture.yaml` | ||
| - flows/error states/trust boundaries/sensitive-data handling -> `data-flow.yaml` | ||
| - schemas/entities/lifecycles/retention-compliance notes -> `data-model.yaml` | ||
| - rules/enforcement -> `invariants.yaml` | ||
| - imports/layers -> `dependency-rules.yaml` | ||
| - cross-scope APIs/schemas/events -> `contracts.yaml` | ||
| - risks/failure modes -> `risk-register.yaml` | ||
| - cross-scope APIs/schemas/events/persistence-deployment-auth-telemetry boundaries -> `contracts.yaml` | ||
| - risks/failure modes/affected refs/recommended actions -> `risk-register.yaml` | ||
| - design drift/deferred decisions -> `design-issues.yaml` | ||
| - tests/gaps/priorities -> `testing-strategy.yaml` | ||
| - tests/quality-attribute coverage/gaps/priorities/operability checks -> `testing-strategy.yaml` | ||
| - workflow/checklists -> `change-guide.yaml` |
@@ -62,14 +62,14 @@ --- | ||
| - `validation-baseline`: command status, blockers, recommended validation order. | ||
| - `project-intent`: goals, users, journeys, non-goals, constraints, assumptions. | ||
| - `architecture`: components, architecture style, side-effect boundaries, high-level flow refs. | ||
| - `data-flow`: typed flow graph/steps, inputs, outputs, error states. | ||
| - `data-model`: entities, IDs, schemas, relationships, lifecycles, serialized formats. | ||
| - `project-intent`: product goal, users, journeys, must-have features, non-goals, constraints, assumptions, open questions, success metrics, prioritized quality attributes, operating constraints, risk areas. | ||
| - `architecture`: components, architecture style, style rationale, alternatives/tradeoffs, side-effect boundaries, deployment/operating shape, reliability expectations, observability expectations, security assumptions, high-level flow refs. | ||
| - `data-flow`: typed flow graph/steps, trust boundaries, sensitive-data handling steps, inputs, outputs, error states, degradation/recovery notes. | ||
| - `data-model`: entities, IDs, schemas, relationships, lifecycles, serialized formats, retention/compliance notes. | ||
| - `invariants`: rules, forbidden states, enforcement locations, invariant-test refs. | ||
| - `dependency-rules`: layers, allowed/forbidden dependencies, violations, coupling hotspots. | ||
| - `design-issues`: structural drift, deferred decisions, ambiguity, ownership gaps. | ||
| - `risk-register`: failure modes, severity/confidence, affected refs, suggested tests/fixes. | ||
| - `contracts`: cross-scope APIs, schemas, events, generated clients, DB/file/deployment/env contracts. | ||
| - `testing-strategy`: test topology, coverage gaps, risk-to-test priorities. | ||
| - `risk-register`: failure modes, severity/confidence, affected refs, mitigations/recommended actions, suggested tests/fixes. | ||
| - `contracts`: cross-scope APIs, schemas, events, generated clients, DB/file/deployment/env/auth/telemetry contracts. | ||
| - `testing-strategy`: test topology, quality-attribute coverage, coverage gaps, risk-to-test priorities, operability checks. | ||
| - `change-guide`: workflow routing and checklists; references owner artifacts, duplicates no facts. | ||
| - `adr`: structured decision records with bounded prose fields. | ||
| - `adr`: structured decision records with bounded prose fields, including alternatives and consequences for major design choices. | ||
| - `agent-operating-guide`: structured source for agent operating rules. Root `AGENTS.md` may mirror this in compact harness-readable Markdown when produced by safe-start or codebase-recon Pass 6. | ||
@@ -113,5 +113,7 @@ | ||
| 1. Reuse existing IDs whenever the semantic object is the same, even if name/path changed. | ||
| 2. New IDs use deterministic slugs from owner scope + semantic name: `risk:<slug>`, `entity:<slug>`, `component:<slug>`, etc. | ||
| 3. If two objects slug-collide, append shortest stable discriminator from path/component/contract, not a random suffix. | ||
| 4. Never renumber IDs because order changed. | ||
| 2. New record IDs use deterministic slugs from owner scope + semantic name: `risk:<slug>`, `entity:<slug>`, `component:<slug>`, etc. | ||
| 3. Envelope `artifact_id` values use `repo:<artifact-slug>` for repo-level artifacts and `<scope.id>/<artifact-slug>` for scoped artifacts, e.g. `repo:architecture` and `scope:packages/ai/architecture`. | ||
| 4. Never append an artifact slug to a scope ID with a second colon; `scope:packages/ai:architecture` is invalid. | ||
| 5. If two objects slug-collide, append shortest stable discriminator from path/component/contract, not a random suffix. | ||
| 6. Never renumber IDs because order changed. | ||
@@ -178,2 +180,3 @@ ### 4. Upsert semantics | ||
| - Do not write README or prose docs as workflow artifacts. Root `AGENTS.md` is allowed as compact harness interoperability output. | ||
| - Make decision-driving quality attributes explicit early. Capture proportional depth, but do not skip the fields; use concise notes or empty arrays only when clearly not applicable and justified by context. | ||
| - Design data flow first, then boundaries, then scaffold. | ||
@@ -191,10 +194,10 @@ - Stop for approval after intent, data flow, architecture/scaffold plan, and vertical-slice plan unless user explicitly requested implementation. | ||
| 1. Intent (`/safe-start-01-intent`): write `project-intent.yaml`, initial `repo-inventory.yaml`, optional `scopes.yaml`. | ||
| 2. Data flow (`/safe-start-02-data-flow`): write `data-flow.yaml`, `data-model.yaml`, `invariants.yaml`. | ||
| 3. Architecture (`/safe-start-03-architecture`): write `architecture.yaml`, `dependency-rules.yaml`, `design-issues.yaml`, `risk-register.yaml`, `adr.yaml`. | ||
| 4. Contract docs (`/safe-start-04-contract-docs`): write `change-guide.yaml`, `testing-strategy.yaml`, optional `contracts.yaml`, `security`/`deployment` as contract records if needed, `agent-operating-guide.yaml`, and root `AGENTS.md`. | ||
| 5. Scaffold plan (`/safe-start-05-scaffold-plan`): output plan in chat only; after approval create files. | ||
| 6. Validation baseline (`/safe-start-06-validation`): write `validation-baseline.yaml` from actual commands/status. | ||
| 7. Thin vertical slice (`/safe-start-07-vertical-slice`): implement one minimal slice; update structured artifacts only for durable semantic changes. | ||
| 8. Handoff (`/safe-start-08-handoff`): update `change-guide.yaml`, `risk-register.yaml`, `repo-inventory.yaml`, `design-issues.yaml`, `scopes.yaml`. | ||
| 1. Intent (`/safe-start-01-intent`): write `project-intent.yaml`, initial `repo-inventory.yaml`, optional `scopes.yaml`; explicitly capture prioritized quality attributes, operating constraints, success metrics, and risk areas. | ||
| 2. Data flow (`/safe-start-02-data-flow`): write `data-flow.yaml`, `data-model.yaml`, `invariants.yaml`; surface trust boundaries, sensitive data, failure/degradation states, and retention/compliance implications. | ||
| 3. Architecture (`/safe-start-03-architecture`): write `architecture.yaml`, `dependency-rules.yaml`, `design-issues.yaml`, `risk-register.yaml`, `adr.yaml`; require style rationale, alternatives/tradeoffs, reliability expectations, observability expectations, security assumptions, and ADR linkage for major decisions. | ||
| 4. Contract docs (`/safe-start-04-contract-docs`): write `change-guide.yaml`, `testing-strategy.yaml`, `contracts.yaml` whenever the project has inter-process, persistence, deployment, env, auth, or external integration boundaries, `agent-operating-guide.yaml`, and root `AGENTS.md`; include quality-attribute verification and operability expectations. | ||
| 5. Scaffold plan (`/safe-start-05-scaffold-plan`): output plan in chat only; after approval create files. Plan must preserve architecture constraints and first-slice validation path. | ||
| 6. Validation baseline (`/safe-start-06-validation`): write `validation-baseline.yaml` from actual commands/status; include schema/docs validation expectations and blockers, especially legacy artifacts missing now-required fields. | ||
| 7. Thin vertical slice (`/safe-start-07-vertical-slice`): implement one minimal slice that exercises a primary journey and at least one critical quality attribute or operating constraint; update structured artifacts only for durable semantic changes. | ||
| 8. Handoff (`/safe-start-08-handoff`): update `change-guide.yaml`, `risk-register.yaml`, `repo-inventory.yaml`, `design-issues.yaml`, `scopes.yaml`; ensure unresolved quality/security/reliability/operability gaps are captured for `safe-change`. | ||
@@ -205,8 +208,11 @@ All-in-one shortcut: `/safe-start-all` runs the pass sequence with approval gates unless implementation was explicitly requested. | ||
| - `project-intent.yaml`: `intent.product_goal`, `target_users`, `primary_journeys`, `must_have_features`, `non_goals`, `constraints`, `assumptions`, `open_questions`. | ||
| - `data-flow.yaml`: `flows` with triggers, inputs, ordered steps, outputs, error states, risk refs. | ||
| - `data-model.yaml`: `entities`, `lifecycles`, `serialized_formats`. | ||
| - `project-intent.yaml`: `intent.product_goal`, `intent.target_users`, `intent.primary_journeys`, `intent.must_have_features`, `intent.non_goals`, `intent.constraints`, `intent.assumptions`, `intent.open_questions`, `intent.quality_attributes`, `intent.operating_constraints`, `intent.success_metrics`, `intent.risk_areas`. | ||
| - `data-flow.yaml`: `flows` with `trigger`, `inputs`, ordered `steps`, `outputs`, `error_states`, `trust_boundaries`, `sensitive_data`, and `risk_refs`. | ||
| - `data-model.yaml`: `entities`, `lifecycles`, `serialized_formats`; include retention/compliance notes when they influence architecture or operations. | ||
| - `invariants.yaml`: invariant records with enforcement status and locations. | ||
| - `architecture.yaml`: style, components, boundaries, dependency direction, execution flow refs. | ||
| - `contracts.yaml`: owner/consumer contract records for APIs, schemas, events, generated clients, persistence, deployment, env, CLI. | ||
| - `validation-baseline.yaml`: command records with cwd, status, last_run, blockers, recommended order. | ||
| - `architecture.yaml`: `architecture.style`, `architecture.style_rationale`, `architecture.alternatives_considered`, `architecture.boundaries`, `architecture.reliability_expectations`, `architecture.observability_expectations`, `architecture.security_assumptions`, plus `components`, `dependency_direction`, `execution_flows`, `side_effect_boundaries`. | ||
| - `risk-register.yaml`: risk records with `affected_refs`, evidence-backed severity/confidence, and `recommended_action`; include quality/security/reliability risks when relevant. | ||
| - `testing-strategy.yaml`: `test_structure`, `quality_attribute_coverage`, `coverage_gaps`, `risk_to_test_priorities`, `known_blockers`, optional `operability_checks`; connect important risks and quality attributes to verification. | ||
| - `contracts.yaml`: owner/consumer contract records for APIs, schemas, events, generated clients, persistence, deployment, env, auth, telemetry, or CLI boundaries. | ||
| - `adr.yaml`: ADR records for major architecture choices with context, decision, alternatives, and consequences. | ||
| - `validation-baseline.yaml`: command records with cwd, status, last_run, blockers, recommended order; include docs/schema validation when the workflow introduces or changes structured artifacts. |
@@ -112,5 +112,7 @@ --- | ||
| 1. Reuse existing IDs whenever the semantic object is the same, even if name/path changed. | ||
| 2. New IDs use deterministic slugs from owner scope + semantic name: `risk:<slug>`, `entity:<slug>`, `component:<slug>`, etc. | ||
| 3. If two objects slug-collide, append shortest stable discriminator from path/component/contract, not a random suffix. | ||
| 4. Never renumber IDs because order changed. | ||
| 2. New record IDs use deterministic slugs from owner scope + semantic name: `risk:<slug>`, `entity:<slug>`, `component:<slug>`, etc. | ||
| 3. Envelope `artifact_id` values use `repo:<artifact-slug>` for repo-level artifacts and `<scope.id>/<artifact-slug>` for scoped artifacts, e.g. `repo:architecture` and `scope:packages/ai/architecture`. | ||
| 4. Never append an artifact slug to a scope ID with a second colon; `scope:packages/ai:architecture` is invalid. | ||
| 5. If two objects slug-collide, append shortest stable discriminator from path/component/contract, not a random suffix. | ||
| 6. Never renumber IDs because order changed. | ||
@@ -117,0 +119,0 @@ ### 4. Upsert semantics |
No alert changes
Improved metrics
- Total package byte prevSize
183978
30.63%- Number of package files
66
3.13%- Lines of code
1516
42.48%- Number of lines in readme file
156
1.3%No dependency changes