spec+plan: multi-repo efforts — hub-repo state, repo-tagged tasks, per-repo PRs (0.15.1)

[OriNachum]

What

Exported spec + plan for the multi-repo efforts increment (0.15.1 — docs
and state only, no CLI changes ship here), produced by a dogfooded
/scope → /think → /spec-to-plan run:

• docs/specs/2026-07-06-devague-multi-repo-efforts.md — the converged frame
  (19 claims, 10 honesty conditions, 5 resolved questions, 1 non-blocking park).
• docs/plans/2026-07-06-devague-multi-repo-efforts.md — the converged plan
  (8 tasks over 6 file-disjoint waves, 3 recorded risks).
• .devague/frames/… + .devague/plans/… state JSON as the evidence trail;
  .devague/current_plan pointer updated.

The decided shape (all user-confirmed)

• Pain points (from the last Colleague-assisted effort, all four): no shared
  convergence, no task-to-repo mapping, manual fan-out mechanics, no cross-repo
  review coherence.
• State home: the effort's hub repo holds the single .devague/
  frame+plan; the cwd-relative store is unchanged.
• Granularity: one plan per effort with repo-tagged tasks — one
  convergence gate, one dependency graph across repos; no meta-frame layer.
• Boundary (Expose plan dependency waves as deterministic metadata, not orchestration #20): the repo target is descriptive metadata the operator
  resolves — the CLI never clones, validates paths, or manages worktrees.
• Gate 3: one final PR per touched repo, reviewed together; cross-repo
  dependencies are satisfied at worktree-merge time, not PR-merge time.
• Sequencing: implementation rides the spec+plan: sharper end-to-end method — scope move, per-item instructions, sharper exports, guided fanout #53 carriers (per-item instructions
  t2/t5, enriched waves t9) and lands after t1–t14 — the committed spec+plan: sharper end-to-end method — scope move, per-item instructions, sharper exports, guided fanout #53 plan
  is not reopened.

Notes

• Merge-order note: versioned 0.15.1 assuming the in-flight 0.15.0 skills PR
  merges first; if this merges first the version simply skips 0.15.0.

• Dogfooding found a CLI gap: a parked unknown_blocking has no
  unpark/resolve move (the convergence.py hint suggests moves that can't
  clear it) — recovered by replaying the frame; issue to follow.

• uv run pytest -n auto: 290 passed. markdownlint-cli2: clean on both
  exports and the changelog.

• devague (Claude)

[OriNachum]

/agentic_review

[qodo-code-review]

PR Summary by Qodo

Export multi-repo efforts spec/plan + hub-repo state artifacts (0.15.1)

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Export multi-repo efforts spec + build plan (docs-only; no CLI behavior changes).
• Commit hub-repo .devague/ frame/plan JSON and update current_plan pointer.
• Bump project version to 0.15.1 and document the release in CHANGELOG.

Diagram

graph TD
  A["Operator run\n(/scope→/think→/spec-to-plan)"] --> B[("Hub repo\n.devague state")]
  B --> C["Frame JSON"] --> D["Spec export\n(docs/specs)"] --> E["Plan export\n(docs/plans)"] --> F["Release notes\nCHANGELOG"] --> G["Project version\npyproject.toml"]
  B --> H["current_plan\npointer"]
  subgraph Legend
    direction LR
    _proc["Process"] ~~~ _db[("State store")] ~~~ _doc["Doc/Artifact"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Docs-only export (omit `.devague/*` JSON from git)

• ➕ Smaller diffs and less churn from machine-produced state files
• ➕ Avoids committing potentially noisy internal evidence artifacts
• ➖ Loses the verifiable evidence trail for the dogfooded run
• ➖ Harder to reproduce or audit the converged frame/plan state

2. Single combined artifact (spec+plan in one markdown file)

• ➕ One file to read and review
• ➕ Reduces duplication across artifacts
• ➖ Blurs the boundary between invariant spec and execution plan
• ➖ Harder to diff/speculate about plan evolution independently

3. Store plan/spec as generated release assets instead of repo files

• ➕ Keeps repo clean while still publishing artifacts
• ➕ Avoids frequent updates to docs directories
• ➖ Artifacts become harder to discover/track alongside code
• ➖ Weakens the “state is in the hub repo” operational model

Recommendation: Keep the PR’s current approach: committing both the exported markdown artifacts and the .devague state JSON makes the dogfooded run auditable and preserves the hub-repo-as-source-of-truth model. The main tradeoff (larger diffs) is acceptable here because this increment explicitly ships docs+state only.

Files changed (7) +705 / -2

Documentation (3) +155 / -0

CHANGELOG.mdDocument 0.15.1 as docs/state-only multi-repo efforts export +17/-0

Document 0.15.1 as docs/state-only multi-repo efforts export

• Adds a 0.15.1 entry describing the exported spec/plan artifacts, the decided multi-repo shape, and the explicit note that no CLI changes ship in this release.

CHANGELOG.md

2026-07-06-devague-multi-repo-efforts.mdAdd build plan markdown export for multi-repo efforts +77/-0

Add build plan markdown export for multi-repo efforts

• Introduces the human-readable build plan export listing tasks t1–t8, dependencies, acceptance criteria, and risks for the multi-repo efforts increment.

docs/plans/2026-07-06-devague-multi-repo-efforts.md

2026-07-06-devague-multi-repo-efforts.mdAdd spec markdown export for multi-repo efforts +61/-0

Add spec markdown export for multi-repo efforts

• Introduces the spec export summarizing audience, before/after, requirements, honesty conditions, boundaries, non-goals, assumptions, and decisions for multi-repo efforts.

docs/specs/2026-07-06-devague-multi-repo-efforts.md

Other (4) +550 / -2

current_planPoint current plan to devague-multi-repo-efforts +1/-1

Point current plan to devague-multi-repo-efforts

• Updates the '.devague/current_plan' pointer to reference the newly exported multi-repo efforts plan slug.

.devague/current_plan

devague-multi-repo-efforts.jsonAdd exported frame state for multi-repo efforts +268/-0

Add exported frame state for multi-repo efforts

• Adds a new exported frame JSON capturing the converged claims, honesty conditions, decisions, and parked vagueness for the multi-repo efforts increment.

.devague/frames/devague-multi-repo-efforts.json

devague-multi-repo-efforts.jsonAdd exported plan state (8 tasks, risks) for multi-repo efforts +280/-0

Add exported plan state (8 tasks, risks) for multi-repo efforts

• Adds a new exported plan JSON with targets, the 8-task dependency graph, and recorded risks for implementing repo-tagged tasks and hub-repo state assumptions.

.devague/plans/devague-multi-repo-efforts.json

pyproject.tomlBump package version to 0.15.1 +1/-1

Bump package version to 0.15.1

• Updates the project version from 0.14.1 to 0.15.1 to align with the new docs/state export release.

pyproject.toml