@pieai/pro-gov 0.4.3 → 0.4.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -58
- package/assets/docs/reference/adoption/adoption-playbook.md +16 -68
- package/assets/docs/reference/adoption/recommended-agent-tooling.md +21 -118
- package/assets/integrations/mattpocock-skills.md +27 -130
- package/assets/profiles/doc-only/manifest.yml +1 -6
- package/assets/profiles/doc-only/profile.md +1 -2
- package/assets/profiles/engineering-runtime/manifest.yml +1 -5
- package/assets/profiles/engineering-runtime/profile.md +3 -14
- package/assets/starter/AGENTS.template.md +3 -7
- package/assets/starter/docs/governance/agents-routing/doc-only-v0.9.md +2 -4
- package/assets/starter/docs/governance/agents-routing/engineering-runtime-v0.9.md +3 -21
- package/assets/starter/docs/governance/boundary.md +4 -7
- package/assets/starter/docs/governance/ssot-v0.9.md +3 -4
- package/assets/starter/docs/reference/documentation-map.md +4 -4
- package/cli-guide.md +16 -40
- package/dist/cli.js +185 -709
- package/package.json +2 -2
- package/assets/docs/reference/adoption/agent-workflow-methodology-comparison.md +0 -331
- package/assets/integrations/compound-engineering.md +0 -164
- package/assets/integrations/directed-development.md +0 -46
- package/assets/integrations/ponytail.md +0 -161
- package/assets/integrations/superpowers.md +0 -107
- package/assets/starter/.agents/hooks.json +0 -26
- package/assets/starter/.claude/settings.json +0 -26
- package/assets/starter/.codex/hooks.json +0 -28
|
@@ -9,9 +9,6 @@ Use for code-heavy projects: apps, games, runtimes, services, browser products,
|
|
|
9
9
|
- `docs/governance/ssot-v0.9.md`
|
|
10
10
|
- external AI-in-the-Loop policy linked by target projects under `docs/policy/shared-rules/ai-in-the-loop.md`
|
|
11
11
|
- `docs/governance/agents-routing/engineering-runtime-v0.9.md`
|
|
12
|
-
- `integrations/superpowers.md`
|
|
13
|
-
- `integrations/compound-engineering.md`
|
|
14
|
-
- `integrations/directed-development.md`
|
|
15
12
|
- `integrations/mattpocock-skills.md`
|
|
16
13
|
- starter `docs/governance/` and `docs/policy/` templates
|
|
17
14
|
|
|
@@ -30,8 +27,7 @@ Each project must define:
|
|
|
30
27
|
- product canon
|
|
31
28
|
- stack-specific rules
|
|
32
29
|
- game/app-specific lane wording
|
|
33
|
-
-
|
|
34
|
-
- Compound Engineering plugin body
|
|
30
|
+
- external workflow plugin bodies
|
|
35
31
|
- mattpocock/skills body
|
|
36
32
|
|
|
37
33
|
## Automation Boundary
|
|
@@ -44,14 +40,7 @@ content under the target project's ownership. Optional Lefthook and CI
|
|
|
44
40
|
guardrails are also consumer-owned when installed; `doc-gov doctor` checks that
|
|
45
41
|
their required governance commands remain present.
|
|
46
42
|
|
|
47
|
-
Engineering-runtime starters also include Codex, Claude Code, and Antigravity
|
|
48
|
-
Stop hooks that call `pro-gov host-hook`. Use `pro-gov doctor --strict-hooks`
|
|
49
|
-
after sync to confirm the host configs are wired. The starter default is
|
|
50
|
-
`--compound-gate-mode off`, so the hook does not interrupt the main session
|
|
51
|
-
unless the project explicitly switches to `lite` or `strict`. Even when enabled,
|
|
52
|
-
the hook does not replace verification, tests, or `ce-compound` itself.
|
|
53
|
-
|
|
54
43
|
For non-trivial engineering work, run `pro-gov learn recall --query "<task
|
|
55
44
|
summary>"` before changing files so existing `docs/solutions/**` and
|
|
56
|
-
`CONCEPTS.md` lessons can shape the work
|
|
57
|
-
|
|
45
|
+
`CONCEPTS.md` lessons can shape the work. After verified work, use the
|
|
46
|
+
`capture-learning` skill only when a reusable lesson exists.
|
|
@@ -40,13 +40,9 @@
|
|
|
40
40
|
|
|
41
41
|
- Name this project's adopted profile: `engineering-runtime` or `doc-only`.
|
|
42
42
|
- Point to the chosen agents-routing file from `docs/governance/agents-routing/`.
|
|
43
|
-
-
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
- Engineering projects should have PGS Stop hooks wired for Codex, Claude Code, and Antigravity. Starter hooks default to `--compound-gate-mode off`; opt into `lite` or `strict` only when this project wants runtime exit-gate reminders. Before final reporting after completed engineering work, report `Compound Gate: ran ce-compound -> <path>`, `Compound Gate: ran fallback capture -> <path>`, or `Compound Gate: skipped -> <reason>`.
|
|
47
|
-
- Use fallback capture only when the current host cannot load Compound Engineering; run `pro-gov learn capture --title "<learning title>" --summary "<reusable lesson>"` so Learning Recall can find the lesson later.
|
|
48
|
-
- Doc-only projects should say that Superpowers TDD and Directed Development are not enabled by default.
|
|
49
|
-
- External workflow systems such as Superpowers or GStack run inside the lane selected by this router. They must not replace this project router.
|
|
43
|
+
- Before non-trivial work, use Learning Recall. After verified work, use `capture-learning` only when a non-obvious reusable lesson exists.
|
|
44
|
+
- Do not install Stop/SubagentStop workflow reminder hooks.
|
|
45
|
+
- Doc-only projects should say that engineering test workflows are not enabled by default.
|
|
50
46
|
|
|
51
47
|
<!-- PGS-ROUTER:END -->
|
|
52
48
|
|
|
@@ -24,7 +24,7 @@ superseded_by: null
|
|
|
24
24
|
|
|
25
25
|
Shared routing algorithm for non-runtime projects such as AI media, IP development, research, and asset governance workspaces.
|
|
26
26
|
|
|
27
|
-
This route does not use
|
|
27
|
+
This route does not use engineering test workflows by default.
|
|
28
28
|
|
|
29
29
|
## Core Flow
|
|
30
30
|
|
|
@@ -52,7 +52,6 @@ flowchart TD
|
|
|
52
52
|
## Rules
|
|
53
53
|
|
|
54
54
|
- Do not ask whether the task needs TDD unless the project has actual runtime code.
|
|
55
|
-
- Do not trigger Directed Development unless the project explicitly opts in.
|
|
56
55
|
- Prefer SSOT, provenance, and approval clarity over engineering ceremonies.
|
|
57
56
|
- Use AI-in-the-Loop for evidence: inspect source, change one thing, verify the target document or asset path.
|
|
58
57
|
|
|
@@ -76,8 +75,7 @@ written as Markdown. Governed docs record decisions, plans, references, policies
|
|
|
76
75
|
and workspace truth. Product artifacts stay in the project package or workbench
|
|
77
76
|
unless the project explicitly opts them into doc-gov.
|
|
78
77
|
|
|
79
|
-
##
|
|
78
|
+
## Host Adapter Boundary
|
|
80
79
|
|
|
81
|
-
This route runs before external workflow systems such as Superpowers or GStack.
|
|
82
80
|
Host-specific adapters such as `CLAUDE.md` may adapt the route for a specific AI
|
|
83
81
|
client, but they must not replace the project `AGENTS.md` route.
|
|
@@ -32,12 +32,8 @@ This file decides **how to choose a workflow**, not what the project is currentl
|
|
|
32
32
|
flowchart TD
|
|
33
33
|
A["Task arrives"] --> B["Read project router and current work"]
|
|
34
34
|
B --> C["Classify with local lane profile"]
|
|
35
|
-
C -->
|
|
36
|
-
|
|
37
|
-
E --> C
|
|
38
|
-
D -- "no" --> F["Enter local lane"]
|
|
39
|
-
F --> G["Use matching Superpowers workflow if applicable"]
|
|
40
|
-
G --> H["Use AI-in-the-Loop evidence cycle"]
|
|
35
|
+
C --> F["Enter local lane"]
|
|
36
|
+
F --> H["Use AI-in-the-Loop evidence cycle"]
|
|
41
37
|
H --> I["Record evidence in doc-gov"]
|
|
42
38
|
```
|
|
43
39
|
|
|
@@ -45,16 +41,6 @@ flowchart TD
|
|
|
45
41
|
|
|
46
42
|
Use this router only to pick depth and workflow. Do not use it as a project roadmap.
|
|
47
43
|
|
|
48
|
-
## DD Trigger
|
|
49
|
-
|
|
50
|
-
Use Directed Development only when all are true:
|
|
51
|
-
|
|
52
|
-
- the task is product work
|
|
53
|
-
- it crosses local lanes or shared contracts
|
|
54
|
-
- sequencing risk makes a flat plan unsafe
|
|
55
|
-
|
|
56
|
-
Do not trigger DD for broad mechanical edits, renames, formatting, or ordinary docs migration.
|
|
57
|
-
|
|
58
44
|
## Project-Local Lane Profile
|
|
59
45
|
|
|
60
46
|
Every engineering project must define its own lane profile in `AGENTS.md` or `docs/policy/best-practice-for-this-project.md`.
|
|
@@ -68,11 +54,7 @@ Typical lanes:
|
|
|
68
54
|
|
|
69
55
|
But the shared router must not define project-specific lanes.
|
|
70
56
|
|
|
71
|
-
##
|
|
72
|
-
|
|
73
|
-
This route runs before external workflow systems such as Superpowers or GStack.
|
|
74
|
-
Those systems may provide skills, reviews, browser workflows, or shipping gates,
|
|
75
|
-
but they execute **inside** the lane selected by this route.
|
|
57
|
+
## Host Adapter Boundary
|
|
76
58
|
|
|
77
59
|
Host-specific adapters such as `CLAUDE.md` may adapt the route for a specific AI
|
|
78
60
|
client, but they must not replace the project `AGENTS.md` route.
|
|
@@ -45,8 +45,7 @@ project-specific AI development habits live.
|
|
|
45
45
|
- Product canon, runtime truth, or content truth.
|
|
46
46
|
- Product prompts, generated media notes, or project-package workbench files.
|
|
47
47
|
- Current project plans or active specs.
|
|
48
|
-
-
|
|
49
|
-
- Compound Engineering plugin content.
|
|
48
|
+
- External workflow plugin content.
|
|
50
49
|
|
|
51
50
|
## Put Those Elsewhere
|
|
52
51
|
|
|
@@ -60,7 +59,7 @@ project-specific AI development habits live.
|
|
|
60
59
|
| Product or world truth | `docs/canon/` |
|
|
61
60
|
| Active implementation work | `docs/plans/active/` |
|
|
62
61
|
| Completed proof records | `docs/plans/completed/` |
|
|
63
|
-
|
|
|
62
|
+
| Reusable project learnings | `docs/solutions/**` as learning artifacts |
|
|
64
63
|
| Product artifacts outside governed docs | Project package, workbench, assets, runtime config, or source tree |
|
|
65
64
|
|
|
66
65
|
When unsure, ask this question: is this rule about how the document system works,
|
|
@@ -77,7 +76,5 @@ product packages, workbenches, prompt libraries, source folders, or asset
|
|
|
77
76
|
folders can be product artifacts. Keep those files where the product package
|
|
78
77
|
expects them unless a project explicitly opts them into doc-gov.
|
|
79
78
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
`docs/plans/*` are not governed docs by default. They remain valid project
|
|
83
|
-
artifacts, but their frontmatter belongs to Compound Engineering, not Doc Gov.
|
|
79
|
+
Learning artifacts under `docs/solutions/**` are not governed docs by default.
|
|
80
|
+
They remain searchable project artifacts with their own lightweight metadata.
|
|
@@ -50,13 +50,12 @@ Markdown.
|
|
|
50
50
|
|
|
51
51
|
Extra governed roots are allowed only when a project explicitly opts in.
|
|
52
52
|
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
Learning and optional-tool artifacts are explicitly outside the default Doc Gov
|
|
54
|
+
schema:
|
|
55
55
|
|
|
56
56
|
- `docs/solutions/**`
|
|
57
57
|
- `docs/brainstorms/**`
|
|
58
58
|
- `docs/pulse-reports/**`
|
|
59
|
-
- CE-native root artifacts under `docs/plans/*`
|
|
60
59
|
|
|
61
60
|
PGS plans remain under `docs/plans/active/**` and
|
|
62
61
|
`docs/plans/completed/**`.
|
|
@@ -117,7 +116,7 @@ works for governed docs:
|
|
|
117
116
|
| Project AI/development policy | `docs/policy/` |
|
|
118
117
|
| Product or feature requirement | `docs/specs/` |
|
|
119
118
|
| Step-by-step implementation work | `docs/plans/` |
|
|
120
|
-
|
|
|
119
|
+
| Reusable learning records | `docs/solutions/**`, outside Doc Gov schema |
|
|
121
120
|
| Durable workspace/system truth | `docs/canon/` |
|
|
122
121
|
| How-to guides, architecture maps, tool notes | `docs/reference/` |
|
|
123
122
|
| Retired governed history | `docs/archive/` |
|
|
@@ -40,7 +40,7 @@ Use `AGENTS.md` for startup reading. It should point agents to:
|
|
|
40
40
|
| `docs/specs/completed/` | Completed specs |
|
|
41
41
|
| `docs/plans/active/` | Active implementation plans |
|
|
42
42
|
| `docs/plans/completed/` | Completed execution records |
|
|
43
|
-
| `docs/solutions/` |
|
|
43
|
+
| `docs/solutions/` | Reusable learning records, outside Doc Gov schema |
|
|
44
44
|
| `docs/canon/` | Durable project truth |
|
|
45
45
|
| `docs/reference/` | Guides and references |
|
|
46
46
|
| `docs/archive/` | Retired history |
|
|
@@ -51,6 +51,6 @@ project-package canon, generated media notes, and source-package files stay in
|
|
|
51
51
|
their product/workbench structure unless this project explicitly opts them into
|
|
52
52
|
doc-gov.
|
|
53
53
|
|
|
54
|
-
|
|
55
|
-
`docs/pulse-reports
|
|
56
|
-
|
|
54
|
+
Optional skills may create `docs/solutions/**`, `docs/brainstorms/**`, or
|
|
55
|
+
`docs/pulse-reports/**`. Those are external artifacts, not Doc Gov canonical
|
|
56
|
+
documents.
|
package/cli-guide.md
CHANGED
|
@@ -21,17 +21,15 @@ pro-gov portfolio plan --config /path/to/portfolio.json --target web-app --json
|
|
|
21
21
|
pro-gov portfolio assets-check --config /path/to/portfolio.json --json
|
|
22
22
|
pro-gov portfolio doctor --config /path/to/portfolio.json --json
|
|
23
23
|
pro-gov learn recall --query "release downstream sync" --target .
|
|
24
|
-
pro-gov learn capture --title "
|
|
24
|
+
pro-gov learn capture --title "Reusable learning" --summary "Reusable lesson..." --target .
|
|
25
25
|
pro-gov lens inspect --target .
|
|
26
26
|
pro-gov lens report --target . --out .pro-gov/lens-report.md
|
|
27
27
|
pro-gov lens audit init --target /path/to/project --out audits/project/2026-07-01
|
|
28
28
|
pro-gov lens audit check --dir audits/project/2026-07-01
|
|
29
|
-
pro-gov host-hook --host codex --event Stop --compound-gate-mode off|lite|strict
|
|
30
29
|
pro-gov init --profile engineering-runtime --dry-run
|
|
31
30
|
pro-gov init --profile engineering-runtime --apply
|
|
32
31
|
pro-gov init --profile doc-only --dry-run
|
|
33
32
|
pro-gov sync --check [--profile engineering-runtime|doc-only]
|
|
34
|
-
pro-gov sync --apply-host-hooks --profile engineering-runtime
|
|
35
33
|
pro-gov doctor
|
|
36
34
|
```
|
|
37
35
|
|
|
@@ -45,47 +43,26 @@ Actions references stay packaged but are not installed by default.
|
|
|
45
43
|
but checks project-local seeds such as `AGENTS.md`, project policy, and current
|
|
46
44
|
work for presence only. Optional `lefthook.yml` and CI guardrails remain
|
|
47
45
|
consumer-owned when installed; `doc-gov doctor` validates their required PGS
|
|
48
|
-
commands without requiring byte-for-byte template equality.
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
`sync --apply-host-hooks` is the bounded write path for engineering-runtime
|
|
54
|
-
host configs. It updates only PGS Compound Gate entries and preserves consumer
|
|
55
|
-
`PreToolUse`, other events, other top-level keys, and non-PGS entries inside
|
|
56
|
-
Stop/SubagentStop arrays. All three files are parsed before any write.
|
|
57
|
-
|
|
58
|
-
`learn recall` is the pre-work companion to Compound Engineering's post-work
|
|
59
|
-
`ce-compound` learning records. It searches `docs/solutions/**` and
|
|
46
|
+
commands without requiring byte-for-byte template equality. It infers the
|
|
47
|
+
installed profile when exactly one route exists; `--profile` resolves an empty
|
|
48
|
+
or temporarily ambiguous target. PGS does not install or modify AI-host hooks.
|
|
49
|
+
|
|
50
|
+
`learn recall` searches `docs/solutions/**` and
|
|
60
51
|
`CONCEPTS.md` in the target repository and returns the most relevant prior
|
|
61
52
|
lessons for the current task. Use it before non-trivial implementation,
|
|
62
53
|
debugging, release, architecture, or portfolio-sync work. It is read-only and
|
|
63
54
|
does not require a full local PGS checkout.
|
|
64
55
|
|
|
65
|
-
`learn capture` is the
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
reusable lesson that is not already covered by an existing `docs/solutions/**`
|
|
69
|
-
record:
|
|
56
|
+
`learn capture` is the small native capture path. Use it only after verified
|
|
57
|
+
work produced a reusable lesson that is not already covered by an existing
|
|
58
|
+
`docs/solutions/**` record:
|
|
70
59
|
|
|
71
60
|
```bash
|
|
72
61
|
pro-gov learn capture \
|
|
73
|
-
--title "
|
|
74
|
-
--summary "Capture the
|
|
62
|
+
--title "Keep the reusable lesson searchable" \
|
|
63
|
+
--summary "Capture the lesson so Learning Recall can find it later."
|
|
75
64
|
```
|
|
76
65
|
|
|
77
|
-
Then report:
|
|
78
|
-
|
|
79
|
-
```text
|
|
80
|
-
Compound Gate: ran fallback capture -> docs/solutions/<category>/<file>.md
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
`host-hook` is the cross-host Compound Gate adapter for Codex, Claude Code, and
|
|
84
|
-
Antigravity. `--compound-gate-mode off` is the default and does not interrupt
|
|
85
|
-
the main session. `lite` emits a short continuation prompt when completed
|
|
86
|
-
engineering work lacks a Compound Gate marker. `strict` emits the fuller legacy
|
|
87
|
-
prompt. The same value can be supplied through `PGS_COMPOUND_GATE_MODE`.
|
|
88
|
-
|
|
89
66
|
Full upstream-checkout commands:
|
|
90
67
|
|
|
91
68
|
```bash
|
|
@@ -123,7 +100,7 @@ maintainer checks.
|
|
|
123
100
|
`portfolio assets-check` verifies that the currently recorded lock and managed
|
|
124
101
|
links are healthy. `portfolio doctor` additionally compares each target with the
|
|
125
102
|
current portfolio `assetBundles`, registry hashes, package versions, target-local
|
|
126
|
-
router
|
|
103
|
+
router checks, and optional `hostTooling` requirements. The doctor is
|
|
127
104
|
offline and read-only by default. A dirty product worktree is reported as
|
|
128
105
|
evidence but is not itself a governance failure.
|
|
129
106
|
|
|
@@ -141,14 +118,14 @@ The native tools own fetching and installation. PGS reviews resulting asset
|
|
|
141
118
|
changes, regenerates plans, and verifies the fleet; it does not implement a
|
|
142
119
|
second plugin marketplace or silently accept upstream changes.
|
|
143
120
|
|
|
144
|
-
`lens audit init` creates a raw-first audit package for Project Lens
|
|
145
|
-
|
|
121
|
+
`lens audit init` creates a raw-first audit package for Project Lens reviews.
|
|
122
|
+
For a "read-only project audit", the target repository remains
|
|
146
123
|
read-only, but the audit package is still the required output record. `lens
|
|
147
124
|
audit check` fails when the package is missing required artifacts, when
|
|
148
125
|
artifacts are still marked pending, or when generated template text was not
|
|
149
126
|
replaced with real audit output. It also requires method records for the
|
|
150
|
-
read-only boundary, agent execution, subagent trace, Project Lens
|
|
151
|
-
sources, target status, and audit package status. Use
|
|
127
|
+
read-only boundary, agent execution, subagent trace, Project Lens and simplicity
|
|
128
|
+
review sources, target status, and audit package status. Use
|
|
152
129
|
`lens audit check --mode fresh` when this session must prove it created the raw
|
|
153
130
|
passes; use `--mode reuse` when it only verifies an existing audit package.
|
|
154
131
|
|
|
@@ -163,7 +140,6 @@ pnpm pro-gov init --profile engineering-runtime --dry-run
|
|
|
163
140
|
pnpm pro-gov init --profile engineering-runtime --apply
|
|
164
141
|
pnpm doc-gov scan
|
|
165
142
|
pnpm pro-gov sync --check --profile engineering-runtime
|
|
166
|
-
pnpm pro-gov sync --apply-host-hooks --profile engineering-runtime
|
|
167
143
|
pnpm doc-gov migrate --profile engineering-runtime --check
|
|
168
144
|
pnpm doc-gov doctor
|
|
169
145
|
```
|