vinta-ai-workflows 0.6.1 → 0.7.0-alpha10
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/CHANGELOG.md +714 -0
- package/README.md +21 -13
- package/package.json +8 -8
- package/schemas/README.md +5 -1
- package/schemas/postmortem.v1.schema.json +339 -0
- package/schemas/vinta-ai-workflows-config.v1.schema.json +13 -1
- package/schemas/workflow.v1.schema.json +978 -0
- package/skills/vinta-bootstrap-ai-tools/SKILL.md +9 -1
- package/skills/vinta-derive-skills/SKILL.md +6 -2
- package/skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/scripts/open-pr.sh +0 -0
- package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md +622 -32
- package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md +34 -4
- package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/claude-worktree-write-guard.py +0 -0
- package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/gen-claude-sandbox-settings.sh +0 -0
- package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/gen-compose-worktree-override.sh +0 -0
- package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/sandbox-run.sh +0 -0
- package/skills/vinta-derive-skills/resources/plan-execution/README.md +21 -4
- package/skills/vinta-derive-skills/resources/plan-execution/partials/agent-models.md +30 -3
- package/skills/vinta-derive-skills/resources/plan-execution/partials/commit-strategy/modular.md +27 -14
- package/skills/vinta-derive-skills/resources/plan-execution/partials/commit-strategy/stacked.md +12 -18
- package/skills/vinta-derive-skills/resources/plan-execution/partials/implementer-prompt.md +19 -9
- package/skills/vinta-derive-skills/resources/plan-execution/partials/model-pick.md +25 -9
- package/skills/vinta-derive-skills/resources/plan-execution/partials/parallel-lanes.md +240 -0
- package/skills/vinta-derive-skills/resources/plan-execution/partials/review-layers.md +56 -5
- package/skills/vinta-derive-skills/resources/plan-execution/partials/worktree-seam.md +13 -6
- package/skills/vinta-derive-skills/resources/plan-execution/shell/amend-plan-template.md +17 -12
- package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-phase-template.md +5 -3
- package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-plan-template.md +94 -57
- package/skills/vinta-derive-skills/resources/plan-execution/shell/integrate-phase-template.md +2 -1
- package/skills/vinta-derive-skills/resources/plan-execution/shell/review-phase-template.md +16 -5
- package/skills/vinta-install-ai-tools-setup/resources/setup-ai-tools.mjs +0 -0
package/README.md
CHANGED
|
@@ -48,9 +48,9 @@ After bootstrap, the project ships with **three foundation skills** that take a
|
|
|
48
48
|
└─────────────────┘ Phased Rollout, Touch List, Risks)
|
|
49
49
|
│
|
|
50
50
|
▼
|
|
51
|
-
┌─────────────────┐ one
|
|
52
|
-
│ implement-plan │───►
|
|
53
|
-
└─────────────────┘
|
|
51
|
+
┌─────────────────┐ one branch per phase (independent phases run in
|
|
52
|
+
│ implement-plan │───► parallel lanes) + a tracking dir
|
|
53
|
+
└─────────────────┘ plan/<feature>/phase-1, phase-2, wave-1, ...
|
|
54
54
|
```
|
|
55
55
|
|
|
56
56
|
You also get: an `AGENTS.md` tuned to the codebase — a regular file at the repo root, with per-vendor aliases (`CLAUDE.md`, `.github/copilot-instructions.md`) symlinked to it — project-specific sub-agents and skills derived from the actual stack, and per-vendor wiring so Claude Code / Codex / Cursor / Copilot all see the same artifacts.
|
|
@@ -80,7 +80,7 @@ The bootstrap skills are **one-shot**. They scaffold the project once and are re
|
|
|
80
80
|
- **Goals + Non-goals** — what's in / out of scope.
|
|
81
81
|
- **Guiding Decisions** — feature flag (key, scope, default, flip-on criterion if any), storage shape, tenant scoping, API contract, schema rules. Load-bearing — every phase reaches back here.
|
|
82
82
|
- **Data Model Changes** — migrations + rollout order.
|
|
83
|
-
- **Phased Rollout** — each phase declares: `id`, `title`, `goal`, `
|
|
83
|
+
- **Phased Rollout** — opens with a **Crew** table (the agents this plan is staffed with, each with a role — `implementer` or `reviewer` — and a tier; every implementer keeps one worktree and one session for the whole run, while reviewers read the lane they are reviewing before it is committed), then each phase declares: `id`, `title`, `goal`, `Assigned to` (which crew member takes it — implement-plan resolves their tier to the cheapest available model), `reusable_skills` (other project skills the implementer should invoke), `Changes`, `Tests`, `Acceptance`, plus flags for `is_cross_repo` and `is_flag_removal` (both deferred).
|
|
84
84
|
- **Risk & Rollout Notes**, **Open Questions**, **Touch List**.
|
|
85
85
|
|
|
86
86
|
Phases are sized so the slowest path (e.g. cross-repo producer wiring, external integration approval) starts in Phase 1 and fast in-repo work fills in behind. Large mutation phases get split (`4a / 4b / 4c`) rather than monolithic.
|
|
@@ -105,28 +105,34 @@ Phases are sized so the slowest path (e.g. cross-repo producer wiring, external
|
|
|
105
105
|
- **Layer 3 — independent reviewer**: spawn a fresh `reviewer` agent with no implementation context. Findings triaged BLOCKER / SHOULD-FIX / NIT.
|
|
106
106
|
6. **Fix loop**: each finding → spawn a `fixer` agent (separate session) that re-runs inner + outer loops; orchestrator never edits directly. Repeat until all three layers are clean.
|
|
107
107
|
|
|
108
|
-
**Branch model — one branch per phase,
|
|
108
|
+
**Branch model — one branch per phase, based on that phase's dependencies:**
|
|
109
|
+
|
|
110
|
+
Every phase in the plan declares what it needs (`**Depends on**: Phase 1 (the `BookmarkFolder` model), …`). That line — not the phase's number — decides both when it runs and what it branches from.
|
|
109
111
|
|
|
110
112
|
```bash
|
|
111
|
-
#
|
|
113
|
+
# A phase with no dependencies — branches from the default branch.
|
|
112
114
|
git checkout main && git pull --ff-only
|
|
113
115
|
git checkout -b plan/<feature-kebab>/phase-1
|
|
114
|
-
# implementer's commits land here
|
|
115
116
|
git push -u origin plan/<feature-kebab>/phase-1
|
|
116
117
|
|
|
117
|
-
#
|
|
118
|
+
# A phase depending on exactly one phase — branches from it.
|
|
118
119
|
git checkout plan/<feature-kebab>/phase-1
|
|
119
120
|
git checkout -b plan/<feature-kebab>/phase-2
|
|
120
121
|
git push -u origin plan/<feature-kebab>/phase-2
|
|
121
122
|
|
|
122
|
-
#
|
|
123
|
+
# A phase depending on several — branches from a merge of them.
|
|
124
|
+
git checkout -B plan/<feature-kebab>/integ-4 plan/<feature-kebab>/phase-2
|
|
125
|
+
git merge --no-ff plan/<feature-kebab>/phase-3
|
|
126
|
+
git checkout -b plan/<feature-kebab>/phase-4
|
|
123
127
|
```
|
|
124
128
|
|
|
125
|
-
Each phase's PR (or branch, depending on the project's PR policy captured at bootstrap) targets
|
|
129
|
+
Each phase's PR (or branch, depending on the project's PR policy captured at bootstrap) targets its own base, not `main`. This keeps the diff per PR scoped to a single phase, makes review manageable, and lets the team merge as approvals land. A plan whose phases form a chain produces exactly the classic stack; a plan with independent phases produces several short stacks, reunited by per-wave integration branches (`plan/<feature-kebab>/wave-<N>`).
|
|
130
|
+
|
|
131
|
+
**Parallel phases.** Because the plan carries a dependency graph, `implement-plan` implements independent phases **at the same time** — one worktree lane per phase in flight, each with its own dev + test database and compose stack, so concurrent test runs don't collide. A phase starts the moment every phase it depends on is green and a lane frees up; a failed phase blocks only its dependents while the rest of the plan keeps going. On by default (`run_options.implement-plan.parallel_phases`, capped by `max_parallel_lanes`, default 3), it requires `prepare-worktree` and refuses to run rather than silently falling back to sequential when worktrees aren't available. A chain-shaped plan runs one phase at a time — same scheduler, one lane.
|
|
126
132
|
|
|
127
133
|
**Alternative: modular commits.** Teams that prefer one branch + one PR per plan can set `policies.commit_strategy: modular-commits` in `.vinta-ai-workflows.yaml`. Under that mode, every phase pushes its **atomic unit commits** (one per service, use-case wire-up, init export, serializer field, refactor, or bug fix — tests in the same commit as code) to a single `plan/<feature-kebab>` branch; the PR opens once after Phase 1 review and gets updated as later phases push. The third option, `commit_strategy: ask`, prompts `implement-plan` at Step 0 (alongside the existing `pause_between_phases` / `generate_inline_comments` opt-ins) and caches the answer in the tracking file. Default is `stacked-branches` — the model documented above. See [`schemas/vinta-ai-workflows-config.v1.schema.json`](schemas/vinta-ai-workflows-config.v1.schema.json) for the field definition.
|
|
128
134
|
|
|
129
|
-
**Tracking
|
|
135
|
+
**Tracking directory** — `ai-plans/TRACKING_<feature-kebab>/`. The orchestrator writes it from `git diff` + the agent's report (not the agent's narration): `run.md` for run options, the resolved dependency graph, and the lane pool; one `phase-<id>.md` per phase (status, model used, branch, base, wave, e2e+screenshots when applicable, 5–15 line summary); `waves/wave-<N>.md` for each integration merge. It is a directory rather than one file so concurrent lanes never write the same path — each phase's entry is committed on that phase's own branch, which keeps wave merges clean. Acts as the durable context handoff between phase prompts, scoped per phase to its own dependencies. Deleted on plan completion.
|
|
130
136
|
|
|
131
137
|
**Phases the orchestrator never auto-executes:**
|
|
132
138
|
|
|
@@ -218,7 +224,7 @@ The 0.2.0 alpha line adds five foundation skills and restructures plan execution
|
|
|
218
224
|
|
|
219
225
|
- **`handoff` (always)** — writes a session-continuation doc to `.vinta-ai-workflows/handoffs/` so a fresh session, a different agent, or a teammate can resume in-flight work without re-deriving context. Write mode gathers the goal, what's verified vs. still assumed, decisions and the alternatives rejected, landmines, and the single concrete next step **from the repo, never from memory**. Resume mode reads a handoff and re-checks its claims against the repo before trusting them.
|
|
220
226
|
- **`deslop-comments` (always)** — rewrites the comments and doc blocks a task touched into Simple English, stripping AI-slop vocabulary and negative framing. Comment-only: no renames, no behavior change. It's wired into the review flow — `review-phase` Layer 2 gained a comment-hygiene check and dispatches a `fixer` to run this skill on any comment-slop finding — and is also invokable standalone ("deslop these comments").
|
|
221
|
-
- **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and decides per ignored path whether to symlink, copy, or fork (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it.
|
|
227
|
+
- **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and decides per ignored path whether to symlink, copy, or fork (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase.
|
|
222
228
|
- **`thermo-nuclear-code-quality-review` (opt-in)** — a deliberately harsh, on-demand structural-maintainability audit of a diff (abstraction quality, giant files, spaghetti-condition growth) that hunts for "code-judo" reframes collapsing whole branches / helpers / modes / layers rather than polishing them. Read-only — it reports findings and hands each fix to a `fixer`. `review-phase` Layer 3 now applies a condensed version of this lens on every phase and escalates to the full audit only when a phase touches core architecture, crosses ~1,000 lines, or surfaces a structural smell too big to fix inline.
|
|
223
229
|
- **`handoff-to-client` (opt-in, API-only repos)** — generates a self-contained markdown document for the client teams consuming the repo's API: every endpoint / operation added, changed, deprecated, or removed on the current branch vs. the default branch, with request/response shapes derived from the code, auth + error changes, breaking-change flags judged from the strictest plausible client, one realistic example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (required `client_platforms`, plus `api_style` / `api_spec_path` / `output_dir`).
|
|
224
230
|
|
|
@@ -246,7 +252,7 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
|
|
|
246
252
|
| `add-e2e-test` | **opt-in** | Add an e2e test. Body covers e2e framework, page-object pattern, auth/storage-state, seed helpers, tenant scoping, screenshot conventions. |
|
|
247
253
|
| `add-env-var` | **opt-in** | Propagate a new env var through every layer (`.env.example`, build tool envPrefix, build cache hash, app config, AGENTS.md, CI, deploy injection). |
|
|
248
254
|
| [`add-one-off-script`](skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md) | **opt-in** | Author one-off operational scripts (backfills, cleanups, ad-hoc fixes). Ships a `BaseOneOffScript` class (Python + TS) enforcing dry-run default, idempotency, batched DB ops, segmented CSV backups, signal-safe interruption, multi-sink logging. |
|
|
249
|
-
| [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and decides per ignored path whether to **symlink / copy / fork** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it. |
|
|
255
|
+
| [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and decides per ignored path whether to **symlink / copy / fork** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase. |
|
|
250
256
|
| [`thermo-nuclear-code-quality-review`](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md) | **opt-in** | Deliberately harsh structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — hunting "code-judo" reframes that collapse whole branches / helpers / modes / layers. Read-only; hands each fix to `fixer`. `review-phase` Layer 3 runs a condensed lens every phase and escalates to this full audit on core-architecture / ~1000-line / structurally-smelly phases. |
|
|
251
257
|
| `handoff-to-client` | **opt-in** | (API-only repos) Generate a self-contained API-change handoff doc for the client teams consuming the repo's API — every endpoint / operation added / changed / deprecated / removed vs the default branch, with request/response shapes, auth + error changes, breaking-change flags, one example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (client platforms, API style, spec path). |
|
|
252
258
|
|
|
@@ -572,6 +578,8 @@ vinta-ai-workflows/
|
|
|
572
578
|
|
|
573
579
|
`vinta-bootstrap-ai-tools` is the entry point — walks a fresh repo, runs the others in order. The rest can also be invoked individually to refresh a single artifact.
|
|
574
580
|
|
|
581
|
+
The repository is also a pnpm workspace. `packages/` holds **private, unpublished** packages that are not part of what `install` puts in your project — the `files` whitelist excludes the directory. The one worth knowing about is [`packages/vinta-ai-maestro`](packages/vinta-ai-maestro/README.md): an opt-in daemon that executes the `ai-plans/<feature>.workflow.json` files `plan-feature` emits, scheduling independent phases across worktree lanes. Nothing requires it; the skills path runs the same plans with no daemon installed.
|
|
582
|
+
|
|
575
583
|
### Why the `vinta-` prefix?
|
|
576
584
|
|
|
577
585
|
Once installed, these skills sit alongside the user's own project skills in the same `.<vendor>/skills/` directory. The prefix makes ownership obvious in slash menus and on disk: anything under `vinta-*` is managed by this package and gets removed by `uninstall`; anything else belongs to the project.
|
package/package.json
CHANGED
|
@@ -1,15 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vinta-ai-workflows",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0-alpha10",
|
|
4
4
|
"description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"vinta-ai-workflows": "./vinta-ai-workflows.mjs"
|
|
8
8
|
},
|
|
9
|
-
"scripts": {
|
|
10
|
-
"check-ai-models": "node scripts/check-ai-models.mjs",
|
|
11
|
-
"test": "node --test tests/*.test.mjs"
|
|
12
|
-
},
|
|
13
9
|
"devDependencies": {
|
|
14
10
|
"yaml": "^2.4.0"
|
|
15
11
|
},
|
|
@@ -25,10 +21,14 @@
|
|
|
25
21
|
},
|
|
26
22
|
"repository": {
|
|
27
23
|
"type": "git",
|
|
28
|
-
"url": "git+
|
|
24
|
+
"url": "git+https://github.com/vintasoftware/vinta-ai-workflows.git"
|
|
29
25
|
},
|
|
30
26
|
"publishConfig": {
|
|
31
27
|
"access": "public"
|
|
32
28
|
},
|
|
33
|
-
"license": "MIT"
|
|
34
|
-
|
|
29
|
+
"license": "MIT",
|
|
30
|
+
"scripts": {
|
|
31
|
+
"check-ai-models": "node scripts/check-ai-models.mjs",
|
|
32
|
+
"test": "node --test tests/*.test.mjs"
|
|
33
|
+
}
|
|
34
|
+
}
|
package/schemas/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Schemas
|
|
2
2
|
|
|
3
|
-
JSON Schema (Draft 2020-12) contracts for every YAML
|
|
3
|
+
JSON Schema (Draft 2020-12) contracts for every YAML or JSON payload the vinta-ai-workflows toolchain produces or consumes. Every payload carries a `schema_version` integer at its top level; that integer matches the suffix on the schema filename.
|
|
4
4
|
|
|
5
5
|
## Inventory
|
|
6
6
|
|
|
@@ -12,6 +12,10 @@ JSON Schema (Draft 2020-12) contracts for every YAML file the vinta-ai-workflows
|
|
|
12
12
|
| PR-context inline comments | YAML inside the ` ```yaml ... ``` ` fence under `# Comments` of the same file | [`prs-context-comments.v1.schema.json`](prs-context-comments.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |
|
|
13
13
|
| MCP preflight cache | `.vinta-ai-workflows/cache.yaml` (gitignored — per-developer-machine state) | [`mcp-preflight-cache.v1.schema.json`](mcp-preflight-cache.v1.schema.json) | rendered `systematic-debugging` SKILL.md (writes during Phase 0) | rendered `systematic-debugging` SKILL.md (reads at Phase 0 start) |
|
|
14
14
|
| AI model tier table | `ai-tools/skills/plan-feature/resources/ai-models.yaml` (shipped verbatim with the `plan-feature` foundation skill; source: `skills/vinta-derive-skills/resources/foundation-skills/plan-feature/resources/ai-models.yaml`) | [`ai-models.v1.schema.json`](ai-models.v1.schema.json) | nightly `check-ai-models` job ([`scripts/check-ai-models.mjs`](../scripts/check-ai-models.mjs)) → auto-PR | `plan-feature` (per-phase model suggestion) |
|
|
15
|
+
| Workflow (executable plan) | `ai-plans/<feature-kebab>.workflow.json` — **JSON, not YAML** | [`workflow.v1.schema.json`](workflow.v1.schema.json) | `plan-feature` (emitted alongside the human-readable plan) | `vinta-ai-maestro` (the orchestrator daemon) |
|
|
16
|
+
| Plan post-mortem | `.vinta-ai-maestro/runs/<run-id>/postmortem.json` — **JSON, not YAML**; per-run state beside the frozen workflow, copied to `ai-plans/<feature-kebab>.postmortem.json` when a team wants it committed | [`postmortem.v1.schema.json`](postmortem.v1.schema.json) | `vinta-ai-maestro` (once a run has ended) | `plan-feature` (when planning the next feature in the same repo) |
|
|
17
|
+
|
|
18
|
+
> `workflow.v1.schema.json` and `postmortem.v1.schema.json` are the two schemas here that are **generated, not hand-written**. The workflow's source of truth is `packages/vinta-ai-maestro/src/types.ts`; regenerate with `pnpm --filter vinta-ai-maestro schema:gen` and verify with `schema:check`. The post-mortem's is `packages/vinta-ai-maestro/src/postmortem/postmortem.ts`; regenerate with `node --experimental-strip-types src/postmortem/generate.ts` from `packages/vinta-ai-maestro`, verify with the same command plus `--check` — `tests/postmortem.test.ts` runs that byte comparison too. Edit the zod schemas, never the JSON.
|
|
15
19
|
|
|
16
20
|
## Versioning rules
|
|
17
21
|
|
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/postmortem.v1.schema.json",
|
|
4
|
+
"title": "vinta-ai-maestro plan post-mortem",
|
|
5
|
+
"description": "What one finished `vinta-ai-maestro` run learned about the plan that produced it: dependencies that were never used, dependencies discovered missing, same-wave phases that conflicted, and phases whose duration diverged from their wave. Ids, waves, paths, durations and counts only. Lives at `.vinta-ai-maestro/runs/<run-id>/postmortem.json` in a target project, emitted by `vinta-ai-maestro` after a run ends and read by `plan-feature` when planning the next feature in the same repo. GENERATED from packages/vinta-ai-maestro/src/postmortem/postmortem.ts — edit there, not here. See schemas/README.md for versioning rules.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"properties": {
|
|
8
|
+
"$schema": {
|
|
9
|
+
"description": "Optional URL of this schema, for editor validation. Ignored at runtime.",
|
|
10
|
+
"type": "string"
|
|
11
|
+
},
|
|
12
|
+
"schema_version": {
|
|
13
|
+
"type": "number",
|
|
14
|
+
"const": 1,
|
|
15
|
+
"description": "Schema major version. Bumped only on breaking changes."
|
|
16
|
+
},
|
|
17
|
+
"run_id": {
|
|
18
|
+
"type": "string",
|
|
19
|
+
"minLength": 1
|
|
20
|
+
},
|
|
21
|
+
"workflow_id": {
|
|
22
|
+
"type": "string",
|
|
23
|
+
"minLength": 1,
|
|
24
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$",
|
|
25
|
+
"description": "The workflow this run executed."
|
|
26
|
+
},
|
|
27
|
+
"plan_ref": {
|
|
28
|
+
"description": "The human-readable plan the workflow was emitted alongside, if it named one.",
|
|
29
|
+
"type": "string"
|
|
30
|
+
},
|
|
31
|
+
"run": {
|
|
32
|
+
"type": "object",
|
|
33
|
+
"properties": {
|
|
34
|
+
"status": {
|
|
35
|
+
"type": "string",
|
|
36
|
+
"enum": [
|
|
37
|
+
"done",
|
|
38
|
+
"failed"
|
|
39
|
+
]
|
|
40
|
+
},
|
|
41
|
+
"started_at_ms": {
|
|
42
|
+
"type": "integer",
|
|
43
|
+
"minimum": -9007199254740991,
|
|
44
|
+
"maximum": 9007199254740991
|
|
45
|
+
},
|
|
46
|
+
"ended_at_ms": {
|
|
47
|
+
"type": "integer",
|
|
48
|
+
"minimum": -9007199254740991,
|
|
49
|
+
"maximum": 9007199254740991
|
|
50
|
+
},
|
|
51
|
+
"elapsed_ms": {
|
|
52
|
+
"type": "integer",
|
|
53
|
+
"minimum": -9007199254740991,
|
|
54
|
+
"maximum": 9007199254740991
|
|
55
|
+
},
|
|
56
|
+
"node_count": {
|
|
57
|
+
"type": "integer",
|
|
58
|
+
"minimum": 1,
|
|
59
|
+
"maximum": 9007199254740991
|
|
60
|
+
},
|
|
61
|
+
"wave_count": {
|
|
62
|
+
"type": "integer",
|
|
63
|
+
"minimum": 1,
|
|
64
|
+
"maximum": 9007199254740991
|
|
65
|
+
}
|
|
66
|
+
},
|
|
67
|
+
"required": [
|
|
68
|
+
"status",
|
|
69
|
+
"started_at_ms",
|
|
70
|
+
"ended_at_ms",
|
|
71
|
+
"elapsed_ms",
|
|
72
|
+
"node_count",
|
|
73
|
+
"wave_count"
|
|
74
|
+
],
|
|
75
|
+
"additionalProperties": false,
|
|
76
|
+
"description": "The run this describes. Always finished — an unfinished run has no post-mortem."
|
|
77
|
+
},
|
|
78
|
+
"findings": {
|
|
79
|
+
"type": "object",
|
|
80
|
+
"properties": {
|
|
81
|
+
"unused_dependencies": {
|
|
82
|
+
"type": "array",
|
|
83
|
+
"items": {
|
|
84
|
+
"type": "object",
|
|
85
|
+
"properties": {
|
|
86
|
+
"node": {
|
|
87
|
+
"type": "string",
|
|
88
|
+
"minLength": 1,
|
|
89
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$",
|
|
90
|
+
"description": "The dependent phase."
|
|
91
|
+
},
|
|
92
|
+
"depends_on": {
|
|
93
|
+
"type": "string",
|
|
94
|
+
"minLength": 1,
|
|
95
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$",
|
|
96
|
+
"description": "The upstream phase the edge names."
|
|
97
|
+
}
|
|
98
|
+
},
|
|
99
|
+
"required": [
|
|
100
|
+
"node",
|
|
101
|
+
"depends_on"
|
|
102
|
+
],
|
|
103
|
+
"additionalProperties": false,
|
|
104
|
+
"description": "One dependency edge, by id. The plan’s own `artifact` prose is deliberately not carried: the reader has the plan, and this file must stay free of repository text."
|
|
105
|
+
},
|
|
106
|
+
"description": "Edges whose artifact the dependent never needed. Empty on every run today: nothing observes dependency use, and the schedule cannot substitute. See `gaps`."
|
|
107
|
+
},
|
|
108
|
+
"missing_dependencies": {
|
|
109
|
+
"type": "array",
|
|
110
|
+
"items": {
|
|
111
|
+
"type": "object",
|
|
112
|
+
"properties": {
|
|
113
|
+
"node": {
|
|
114
|
+
"type": "string",
|
|
115
|
+
"minLength": 1,
|
|
116
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$",
|
|
117
|
+
"description": "The phase that failed and later passed."
|
|
118
|
+
},
|
|
119
|
+
"depends_on": {
|
|
120
|
+
"type": "string",
|
|
121
|
+
"minLength": 1,
|
|
122
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$",
|
|
123
|
+
"description": "The undeclared phase that landed in between."
|
|
124
|
+
},
|
|
125
|
+
"failed_at_ms": {
|
|
126
|
+
"type": "integer",
|
|
127
|
+
"minimum": -9007199254740991,
|
|
128
|
+
"maximum": 9007199254740991,
|
|
129
|
+
"description": "When the phase first failed."
|
|
130
|
+
},
|
|
131
|
+
"landed_at_ms": {
|
|
132
|
+
"type": "integer",
|
|
133
|
+
"minimum": -9007199254740991,
|
|
134
|
+
"maximum": 9007199254740991,
|
|
135
|
+
"description": "When the undeclared phase reached `done`."
|
|
136
|
+
},
|
|
137
|
+
"passed_at_ms": {
|
|
138
|
+
"type": "integer",
|
|
139
|
+
"minimum": -9007199254740991,
|
|
140
|
+
"maximum": 9007199254740991,
|
|
141
|
+
"description": "When the phase finally reached `done`."
|
|
142
|
+
},
|
|
143
|
+
"gate": {
|
|
144
|
+
"description": "The gate whose recorded result is the evidence: it failed at `failed_at_ms` and passed at `passed_at_ms`. Absent when the run recorded no gate result for the phase and the window came from its status transitions instead — a weaker signal, flagged in `gaps`.",
|
|
145
|
+
"type": "string",
|
|
146
|
+
"minLength": 1,
|
|
147
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$"
|
|
148
|
+
}
|
|
149
|
+
},
|
|
150
|
+
"required": [
|
|
151
|
+
"node",
|
|
152
|
+
"depends_on",
|
|
153
|
+
"failed_at_ms",
|
|
154
|
+
"landed_at_ms",
|
|
155
|
+
"passed_at_ms"
|
|
156
|
+
],
|
|
157
|
+
"additionalProperties": false,
|
|
158
|
+
"description": "A dependency the run discovered and the plan did not declare: the phase failed, an undeclared phase landed, and only then did it pass. The evidence is still ordering — a recorded gate result narrows the window to one gate and rules out an unrelated failure, but it does not prove the undeclared phase is what fixed it. Confirm the edge against the plan before adding it."
|
|
159
|
+
}
|
|
160
|
+
},
|
|
161
|
+
"wave_conflicts": {
|
|
162
|
+
"type": "array",
|
|
163
|
+
"items": {
|
|
164
|
+
"type": "object",
|
|
165
|
+
"properties": {
|
|
166
|
+
"wave": {
|
|
167
|
+
"type": "integer",
|
|
168
|
+
"minimum": 1,
|
|
169
|
+
"maximum": 9007199254740991,
|
|
170
|
+
"description": "The wave whose merge produced the conflict."
|
|
171
|
+
},
|
|
172
|
+
"nodes": {
|
|
173
|
+
"minItems": 2,
|
|
174
|
+
"type": "array",
|
|
175
|
+
"items": {
|
|
176
|
+
"type": "string",
|
|
177
|
+
"minLength": 1,
|
|
178
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$"
|
|
179
|
+
},
|
|
180
|
+
"description": "The phases that both own the contested paths."
|
|
181
|
+
},
|
|
182
|
+
"paths": {
|
|
183
|
+
"type": "array",
|
|
184
|
+
"items": {
|
|
185
|
+
"type": "string"
|
|
186
|
+
},
|
|
187
|
+
"description": "Repository paths that conflicted. Paths, never hunks."
|
|
188
|
+
},
|
|
189
|
+
"fix_rounds": {
|
|
190
|
+
"type": "integer",
|
|
191
|
+
"minimum": 0,
|
|
192
|
+
"maximum": 9007199254740991,
|
|
193
|
+
"description": "Conflict-fixer rounds the resolution took. High is a strong split signal."
|
|
194
|
+
}
|
|
195
|
+
},
|
|
196
|
+
"required": [
|
|
197
|
+
"wave",
|
|
198
|
+
"nodes",
|
|
199
|
+
"paths",
|
|
200
|
+
"fix_rounds"
|
|
201
|
+
],
|
|
202
|
+
"additionalProperties": false,
|
|
203
|
+
"description": "Two same-wave phases that actually fought over the same code at integration."
|
|
204
|
+
}
|
|
205
|
+
},
|
|
206
|
+
"duration_divergences": {
|
|
207
|
+
"type": "array",
|
|
208
|
+
"items": {
|
|
209
|
+
"type": "object",
|
|
210
|
+
"properties": {
|
|
211
|
+
"node": {
|
|
212
|
+
"type": "string",
|
|
213
|
+
"minLength": 1,
|
|
214
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$"
|
|
215
|
+
},
|
|
216
|
+
"wave": {
|
|
217
|
+
"type": "integer",
|
|
218
|
+
"minimum": 1,
|
|
219
|
+
"maximum": 9007199254740991
|
|
220
|
+
},
|
|
221
|
+
"span_ms": {
|
|
222
|
+
"type": "integer",
|
|
223
|
+
"minimum": -9007199254740991,
|
|
224
|
+
"maximum": 9007199254740991,
|
|
225
|
+
"description": "Dispatch to final settle, including fix rounds."
|
|
226
|
+
},
|
|
227
|
+
"wave_baseline_ms": {
|
|
228
|
+
"type": "integer",
|
|
229
|
+
"minimum": -9007199254740991,
|
|
230
|
+
"maximum": 9007199254740991,
|
|
231
|
+
"description": "Median span of the *other* dispatched phases in the same wave."
|
|
232
|
+
},
|
|
233
|
+
"ratio": {
|
|
234
|
+
"type": "number",
|
|
235
|
+
"description": "`span_ms / wave_baseline_ms`, rounded to two decimals."
|
|
236
|
+
},
|
|
237
|
+
"direction": {
|
|
238
|
+
"type": "string",
|
|
239
|
+
"enum": [
|
|
240
|
+
"longer",
|
|
241
|
+
"shorter"
|
|
242
|
+
],
|
|
243
|
+
"description": "`longer`: the phase set the wave’s wall clock on its own."
|
|
244
|
+
}
|
|
245
|
+
},
|
|
246
|
+
"required": [
|
|
247
|
+
"node",
|
|
248
|
+
"wave",
|
|
249
|
+
"span_ms",
|
|
250
|
+
"wave_baseline_ms",
|
|
251
|
+
"ratio",
|
|
252
|
+
"direction"
|
|
253
|
+
],
|
|
254
|
+
"additionalProperties": false,
|
|
255
|
+
"description": "A phase whose real duration was wildly out of line with its wave placement — which is exactly what makes the next plan’s parallelism estimate wrong."
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
},
|
|
259
|
+
"required": [
|
|
260
|
+
"unused_dependencies",
|
|
261
|
+
"missing_dependencies",
|
|
262
|
+
"wave_conflicts",
|
|
263
|
+
"duration_divergences"
|
|
264
|
+
],
|
|
265
|
+
"additionalProperties": false
|
|
266
|
+
},
|
|
267
|
+
"gaps": {
|
|
268
|
+
"type": "array",
|
|
269
|
+
"items": {
|
|
270
|
+
"type": "object",
|
|
271
|
+
"properties": {
|
|
272
|
+
"kind": {
|
|
273
|
+
"type": "string",
|
|
274
|
+
"enum": [
|
|
275
|
+
"dependency_use_unrecorded",
|
|
276
|
+
"gate_result_unrecorded",
|
|
277
|
+
"integration_record_unavailable"
|
|
278
|
+
]
|
|
279
|
+
},
|
|
280
|
+
"needs": {
|
|
281
|
+
"type": "string",
|
|
282
|
+
"description": "What would have to be recorded for the finding to exist."
|
|
283
|
+
},
|
|
284
|
+
"edges": {
|
|
285
|
+
"description": "The edges the gap applies to.",
|
|
286
|
+
"type": "array",
|
|
287
|
+
"items": {
|
|
288
|
+
"type": "object",
|
|
289
|
+
"properties": {
|
|
290
|
+
"node": {
|
|
291
|
+
"type": "string",
|
|
292
|
+
"minLength": 1,
|
|
293
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$",
|
|
294
|
+
"description": "The dependent phase."
|
|
295
|
+
},
|
|
296
|
+
"depends_on": {
|
|
297
|
+
"type": "string",
|
|
298
|
+
"minLength": 1,
|
|
299
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$",
|
|
300
|
+
"description": "The upstream phase the edge names."
|
|
301
|
+
}
|
|
302
|
+
},
|
|
303
|
+
"required": [
|
|
304
|
+
"node",
|
|
305
|
+
"depends_on"
|
|
306
|
+
],
|
|
307
|
+
"additionalProperties": false,
|
|
308
|
+
"description": "One dependency edge, by id. The plan’s own `artifact` prose is deliberately not carried: the reader has the plan, and this file must stay free of repository text."
|
|
309
|
+
}
|
|
310
|
+
},
|
|
311
|
+
"nodes": {
|
|
312
|
+
"description": "The phases the gap applies to.",
|
|
313
|
+
"type": "array",
|
|
314
|
+
"items": {
|
|
315
|
+
"type": "string",
|
|
316
|
+
"minLength": 1,
|
|
317
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$"
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
},
|
|
321
|
+
"required": [
|
|
322
|
+
"kind",
|
|
323
|
+
"needs"
|
|
324
|
+
],
|
|
325
|
+
"additionalProperties": false,
|
|
326
|
+
"description": "A finding this run could not produce, and why. Carried in the artifact rather than thrown or defaulted to an empty list: a reader that treats an empty finding as “nothing happened” has to reach past an explicit statement that nothing was recorded."
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
},
|
|
330
|
+
"required": [
|
|
331
|
+
"schema_version",
|
|
332
|
+
"run_id",
|
|
333
|
+
"workflow_id",
|
|
334
|
+
"run",
|
|
335
|
+
"findings",
|
|
336
|
+
"gaps"
|
|
337
|
+
],
|
|
338
|
+
"additionalProperties": false
|
|
339
|
+
}
|
|
@@ -312,9 +312,21 @@
|
|
|
312
312
|
"default": false
|
|
313
313
|
},
|
|
314
314
|
"use_worktree": {
|
|
315
|
-
"description": "Default answer to Step 0 question (c) — whether `implement-plan` should provision
|
|
315
|
+
"description": "Default answer to Step 0 question (c) — whether `implement-plan` should provision isolated git worktrees (via `prepare-worktree`) and run phase subagents inside them. False = run in the current checkout. True = provision at the start of the plan run: one shared worktree for a sequential run, or one lane per concurrent phase plus an integration worktree when `parallel_phases` is on. Per-run prompt still asks; this is the suggested default shown.",
|
|
316
316
|
"type": "boolean",
|
|
317
317
|
"default": false
|
|
318
|
+
},
|
|
319
|
+
"parallel_phases": {
|
|
320
|
+
"description": "Default answer to Step 0 question (e) — whether `implement-plan` implements independent phases concurrently, one git worktree lane per in-flight phase. The plan's per-phase `**Depends on**:` lines define the graph; a phase starts as soon as every phase it depends on is green. True (default) = run in parallel whenever the graph has a wave wider than one phase. False = one phase at a time. Requires `foundation_skills.prepare-worktree` enabled and `use_worktree` resolving true — several agents cannot share one working tree — and `implement-plan` refuses rather than silently degrading when that is not the case. Per-run prompt still asks; this is the suggested default shown.",
|
|
321
|
+
"type": "boolean",
|
|
322
|
+
"default": true
|
|
323
|
+
},
|
|
324
|
+
"max_parallel_lanes": {
|
|
325
|
+
"description": "Upper bound on how many phases `implement-plan` keeps in flight at once, and therefore how many worktree lanes it provisions. Capped at runtime by the widest wave in the plan's dependency graph — a chain-shaped plan provisions one lane regardless. Each lane costs one runnable checkout (deps + forked dev/test DBs + its own compose project), so raise this only on machines with the disk and CPU for it. Ignored when `parallel_phases` is false.",
|
|
326
|
+
"type": "integer",
|
|
327
|
+
"minimum": 1,
|
|
328
|
+
"maximum": 8,
|
|
329
|
+
"default": 3
|
|
318
330
|
}
|
|
319
331
|
}
|
|
320
332
|
},
|