safe-change
starsforks
How to install safe-change?
prinova/pi-agent-codebase-workflows/safe-change
$npx -y skills add PriNova/pi-agent-codebase-workflows --skill safe-changeStructured safe-change workflow for documented codebases. Reads and writes only canonical YAML artifacts under a resolved structured docs root.
SKILL.md
| 1 | # Safe Change — Structured API Only |
| 2 | |
| 3 | Goal: make changes without architecture drift using canonical structured artifacts. |
| 4 | |
| 5 | |
| 6 | ## Structured Artifact API Contract |
| 7 | |
| 8 | 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 for canonical artifacts. Root `AGENTS.md` remains a harness interoperability file and may be generated/updated only by workflows that explicitly say so. |
| 9 | |
| 10 | Resolved structured docs root: |
| 11 | |
| 12 | Treat `docs/agent/api` as a logical layout rooted at a resolved structured docs root, not a fixed repo path. |
| 13 | |
| 14 | Resolution rules: |
| 15 | 1. Resolve `workspace_root` with `git rev-parse --show-toplevel 2>/dev/null` or fallback to `pwd`. |
| 16 | 2. Canonicalize `workspace_root` before fingerprinting when possible (`realpath`, `pwd -P`, `Path(...).resolve()`, or equivalent). |
| 17 | 3. `safe-start` always creates and uses the initial repo-local root: `<workspace_root>/docs/agent/api`. |
| 18 | 4. `safe-change` uses repo-local only when `<workspace_root>/docs/agent/api` already exists. |
| 19 | 5. Otherwise use the global overlay root: `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. |
| 20 | 6. Compute `<workspace-fingerprint>` exactly from canonical `workspace_root`: strip one leading slash/backslash, replace every slash, backslash, and colon with `-`, then wrap with `--`. This keeps the same workspace stable. |
| 21 | 7. Example: `/data/data/com.termux/files/home/CodeProjects/pi-mono` -> `--data-data-com.termux-files-home-CodeProjects-pi-mono--`. |
| 22 | 8. Do not create new repo-local structured docs in unadopted repos unless the user explicitly asks for repo-local adoption there. |
| 23 | |
| 24 | Logical structured layout under the resolved docs root: |
| 25 | |
| 26 | ```text |
| 27 | repo/ |
| 28 | scopes.yaml |
| 29 | repo-inventory.yaml |
| 30 | project-intent.yaml |
| 31 | architecture.yaml |
| 32 | data-flow.yaml |
| 33 | data-model.yaml |
| 34 | invariants.yaml |
| 35 | dependency-rules.yaml |
| 36 | design-issues.yaml |
| 37 | risk-register.yaml |
| 38 | change-guide.yaml |
| 39 | testing-strategy.yaml |
| 40 | validation-baseline.yaml |
| 41 | contracts.yaml |
| 42 | adr.yaml |
| 43 | agent-operating-guide.yaml |
| 44 | scopes/ |
| 45 | by-path/<repo-relative-path>/... |
| 46 | by-domain/<slug>/... |
| 47 | ``` |
| 48 | |
| 49 | Every structured artifact must conform to `../_shared/references/schemas/common.schema.json` plus its artifact-specific schema. Do not inline, invent, or vary envelope fields. |
| 50 | |
| 51 | Stable IDs required: `scope:*`, `component:*`, `entity:*`, `invariant:*`, `risk:*`, `contract:*`, `flow:*`, `command:*`, `issue:*`, `adr:*`, `testplan:*`. |
| 52 | |
| 53 | Ownership rules: |
| 54 | - `scopes`: scope routing, ownership, cross-scope discovery only. |
| 55 | - `repo-inventory`: file tree, commands index, entry points, external boundaries, configs. |
| 56 | - `validation-baseline`: command status, blockers, recommended validation order. |
| 57 | - `project-intent`: product goal, users, journeys, must-have features, non-goals, constraints, assumptions, open questions, success metrics, prioritized quality attributes, operating constraints, risk areas. |
| 58 | - `architecture`: components, architecture style, style rationale, alternatives/tradeoffs, side-effect boundaries, deployment/operating shape, reliability expectations, observability expectations, security assumptions, high-level flow refs. |
| 59 | - `data-flow`: typed flow graph/steps, trust boundaries, sensitive-data handling steps, inputs, outputs, error states, degradation/recovery notes. |
| 60 | - `data-model`: entities, IDs, schemas, relationships, lifecycles, serialized formats, retention/compliance notes. |
| 61 | - `invariants`: rules, forbidden states, enforcement locations, invariant-test refs. |
| 62 | - `dependency-rules`: layers, allowed/forbidden dependencies, violations, coupling hotspots. |
| 63 | - `design-issues`: structural drift, deferred decisions, ambiguity, ownership gaps. |
| 64 | - `risk-register`: failure modes, severity/confidence, affected refs, mitigations/recommended actions, suggested tests/fixes. |
| 65 | - `contracts`: cross-scope APIs, schemas, events, generated clients, DB/file/deployment/env/auth/telemetry contracts. |
| 66 | - `testing-strategy`: test topology, quality-attribute coverage, coverage gaps, risk-to-test priorities, operability checks. |
| 67 | - `change-guide`: workflow routing and checklists; references owner artifacts, duplicates no facts. |
| 68 | - `adr`: structured decision records with bounded prose fields, including alternatives and consequences for major design choices. |
| 69 | - `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. |
| 70 | |
| 71 | Redundancy rule: define each fact in its owner artifact exactly once. Other artifacts reference IDs. |
| 72 | Current truth rule: canonical YAML artifacts represent current state, not audit history. Remove resolved or superseded records from canonical owner artifacts by default. Keep them only when another live record still refere |
People who liked this also viewed
6 picksType
- requesting-code-reviewUse when completing tasks, implementing major features, or before merging to verify work meets requirementsSkillsJul 2026
- code-reviewSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- receiving-code-reviewUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performativeSkillsJul 2026
- baoyu-format-markdownFormats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks. Use when user asks to "format markdown", "beautify article", "add formatting", or imprSkillsJul 2026
- code-review-excellenceMaster effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing reSkillsJul 2026
- code-review-and-qualityConducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensiSkillsJul 2026
