structured-docs-migration
starsforks
How to install structured-docs-migration?
prinova/pi-agent-codebase-workflows/structured-docs-migration
$npx -y skills add PriNova/pi-agent-codebase-workflows --skill structured-docs-migrationMigration workflow from deprecated prose-style docs/agent Markdown artifacts to canonical structured YAML artifacts under a resolved structured docs root. No fallback or Markdown generation.
SKILL.md
| 1 | # Structured Docs Migration |
| 2 | |
| 3 | Goal: convert legacy prose-style documentation into canonical structured YAML artifacts for agent-first ingestion. |
| 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. `structured-docs-migration` 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`: goals, users, journeys, non-goals, constraints, assumptions. |
| 58 | - `architecture`: components, architecture style, side-effect boundaries, high-level flow refs. |
| 59 | - `data-flow`: typed flow graph/steps, inputs, outputs, error states. |
| 60 | - `data-model`: entities, IDs, schemas, relationships, lifecycles, serialized formats. |
| 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, suggested tests/fixes. |
| 65 | - `contracts`: cross-scope APIs, schemas, events, generated clients, DB/file/deployment/env contracts. |
| 66 | - `testing-strategy`: test topology, coverage gaps, risk-to-test priorities. |
| 67 | - `change-guide`: workflow routing and checklists; references owner artifacts, duplicates no facts. |
| 68 | - `adr`: structured decision records with bounded prose fields. |
| 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 references them or an active migration requires temporary continuity. Use Git history, PRs, issues, or ADRs for audit/history. |
| 73 | Prose rule: bounded prose allowed only in `summary`, `notes`, `rationale`, `context`, `decision`, `recommended_action`, and similar scalar fields. |
| 74 | Scope rule: if focus is path-like, write under `<docs-root>/scopes/by-path/<focus>/`; otherwise under `<docs-root>/scopes/by-domain/<slug>/`. Always update `<docs-root>/repo |
People who liked this also viewed
6 picksType
- azure-costAzure cost management: query costs, forecast spending, optimize to reduce waste. WHEN: \"Azure costs\", \"Azure bill\", \"cost breakdown\", \"how much am I spending\", \"forecast spending\", \"optimizSkillsJul 2026
- pricingWhen the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increaseSkillsJul 2026
- stripe-integrationMulti-harness agentic plugin marketplace for Claude Code, Codex CLI, Cursor, OpenCode, GitHub Copilot, and Gemini CLISkillsJul 2026
- startup-financial-modelingMulti-harness agentic plugin marketplace for Claude Code, Codex CLI, Cursor, OpenCode, GitHub Copilot, and Gemini CLISkillsJul 2026
- tushare-finance专为 Claude Code 设计的 Tushare Pro 金融数据技能包，支持 220+ 个接口，用自然语言获取 A 股行情、财务数据、宏观经济等金融数据。SkillsJul 2026
- azure-pricingFetches real-time Azure retail pricing using the Azure Retail Prices API (prices.azure.com) and estimates Copilot Studio agent credit consumption. Use when the user asks about the cost of any Azure seSkillsJul 2026
