docs(repo): swarm-fundament — onboarding map + AGENTS amend + issue templates #58

Merged

pdurlej merged 2 commits from claude/orders/swarm-fundament into main

2026-05-05 00:26:51 +02:00

claude commented

2026-05-05 00:04:36 +02:00

Collaborator

Canary status: missing — fire canary 3+3 manually before merge

Purpose

Prepare the repo for cold-start swarm agents (claude / codex / glm / antigravity / new arrivals) by adding entry-point guidance, agent onboarding flow, and issue templates with Context Pack discipline.

This PR does NOT do

Does NOT decompose the historical plan into atomic issues — that's separate meta-issue work, opened as follow-ups.
Does NOT implement ADR 0002 — Issue #49 tracks operator setup tasks; CI activation is gated on those.
Does NOT change canary enforcement behavior — ADR 0001 + 0002 stand as-is.
Does NOT create swarm-ready backlog items beyond templates and conventions.
Does NOT address Iskra Issue #56 (Forgejo MCP identity-split) — separate work; this PR documents the workaround (use direct curl with actor PAT) but does not fix the root cause.
Does NOT address Iskra Issue #57 (Antigravity setup) — depends on this fundament; follow-up.
Does NOT update INDEX.md — README is now the entry point; INDEX refresh is a separate small issue.

Changed artifacts

README.md — cold-start entry point and repo map. Rewrote from 24-line stub: "I just walked in. Where do I start?" cookbook, mobile-scannable repo map table, work-flow summary, identity-isolation TL;DR, quality-gates table, where-to-put-new-memory rules.
AGENTS.md — joining cookbook (8 steps) and issue conventions section. Inserted between "What this repo is" and "Current phase" so cold-start agents hit it second. Per Oracle review: §Step 4 documents spec-source whitelist semantics + PR-body disclosure rule; §Issue conventions documents activation-gating lifecycle labels + hard caps.
.forgejo/issue_template/atomic_task.md — spec sources whitelist; extracted-context section (quote 5-30 lines per source so issue self-contained); do-not-read list; allowed-touched-paths whitelist; escape hatch; unknowns / owner questions.
.forgejo/issue_template/meta_decomposition.md — hard cap 5-10 children; produced children carry proposed / needs-triage / not-ready labels by default (NOT ready-for-agent); decomposing agent must post spec sources read disclosure on close.
.forgejo/issue_template/owner_decision.md — questions requiring piotr's input; owner-attention label auto-applied.

Total: 5 files, +602 / -31 (initial commit + Oracle-driven amendments).

Review focus (per Oracle review 2026-05-05)

Please review this as a governance/template PR. Key questions:

Could an unfamiliar agent select work without reading the whole repo? (Test: simulate a cold-start agent reading only README → AGENTS.md §"Joining as a new agent" → an open atomic_task issue. Can they get to a first PR?)
Do the templates prevent oversized or ambiguous issues? (Test: try writing a vague issue using atomic_task.md template — do the required sections force concreteness?)
Is identity isolation clear enough? (Test: can a new agent identify their actor + retrieve PAT + verify push attribution from the cookbook alone?)
Are meta-decomposition tasks constrained enough to avoid backlog spam? (Test: hard cap 5-10 + label proposed default + decomposing agent ≠ implementer + spec-sources-read disclosure — would Antigravity produce 50 issues?)
Are non-goals explicit enough to prevent scope expansion? (This PR does NOT section above; ## Explicit out-of-scope in templates; Do NOT read in atomic_task; escape hatch protocol.)

Oracle review applied

This PR went through Oracle (GPT-5.2 Thinking) review per AGENTS.md §"Oracle escalation discipline" criterion 2 (cross-cutting strategic decision; meta-architecture for swarm enablement). Oracle response in .sisyphus/oracle-paste/swarm-strategy-2026-05-05.md. Key insights applied in commit 2996a7d:

Issues become Context Packs, not pointers — extracted/quoted context in templates
Activation gating via lifecycle labels prevents auto-generated issues from being pickable until human-reviewed
Hard caps (5-10 children/meta) prevent backlog spam
Disclosure (spec sources read) makes silent scope expansion auditable

Oracle confirmed strategy C (hybrid: meta-decomposition skeleton + onboarding) is correct; structural guardrails were the missing piece.

Spec sources read

PLATFORM_CHARTER.md — to understand identity-isolation references
AGENTS.md (pre-amendment) — to identify where cookbook insertion fits without redundancy
decisions/0001-canary-mandatory-pm-cadence.md §Rule 4 + ADR 0002 §Rule 2 — for size-class and iter-cap references in cookbook
INDEX.md — to confirm artifact map references in README
README.md (pre-rewrite, 24-line stub) — to understand what was lost vs. preserved
.sisyphus/oracle-paste/swarm-strategy-2026-05-05.md — Oracle output applied to amendments

Known follow-up

After merge:

Open ONE pilot meta-decomposition issue (target: L4 materialization, since plan §L4 has the most decomposable atomic candidates).
Have one agent decompose into 5-10 proposed atomic tasks.
Review quality of generated children before applying ready-for-agent.
Patch templates / cookbook based on what surfaces.
Then fan out: open additional meta-issues per remaining plan layer with not-ready label until pilot validates.

Test plan

Operator readback: README §"I just walked in" feels correct as the entry point
Operator readback: AGENTS.md §"Joining as a new agent" 8-step flow is the right ordering
Operator readback: activation-gating discipline (proposed → ready-for-agent) feels right for guarding against Antigravity-style spam
Manual canary 3+3 fires + passes (or operator_override per Rule 2)
After merge: claude opens 1 pilot meta-issue (L4 materialization) using new meta_decomposition.md template
After merge: pilot meta-issue is decomposed by one agent into 5-10 proposed atomic issues
Reviewer applies ready-for-agent only after quality check
First swarm-pickable atomic issue produces a clean PR per the cookbook

Canary status: missing — fire canary 3+3 manually before merge ## Purpose Prepare the repo for cold-start swarm agents (claude / codex / glm / antigravity / new arrivals) by adding entry-point guidance, agent onboarding flow, and issue templates with Context Pack discipline. ## This PR does NOT do - Does NOT decompose the historical plan into atomic issues — that's separate meta-issue work, opened as follow-ups. - Does NOT implement ADR 0002 — Issue #49 tracks operator setup tasks; CI activation is gated on those. - Does NOT change canary enforcement behavior — ADR 0001 + 0002 stand as-is. - Does NOT create swarm-ready backlog items beyond templates and conventions. - Does NOT address Iskra Issue #56 (Forgejo MCP identity-split) — separate work; this PR documents the workaround (use direct curl with actor PAT) but does not fix the root cause. - Does NOT address Iskra Issue #57 (Antigravity setup) — depends on this fundament; follow-up. - Does NOT update INDEX.md — README is now the entry point; INDEX refresh is a separate small issue. ## Changed artifacts - **README.md** — cold-start entry point and repo map. Rewrote from 24-line stub: "I just walked in. Where do I start?" cookbook, mobile-scannable repo map table, work-flow summary, identity-isolation TL;DR, quality-gates table, where-to-put-new-memory rules. - **AGENTS.md** — joining cookbook (8 steps) and issue conventions section. Inserted between "What this repo is" and "Current phase" so cold-start agents hit it second. Per Oracle review: §Step 4 documents spec-source whitelist semantics + PR-body disclosure rule; §Issue conventions documents activation-gating lifecycle labels + hard caps. - **`.forgejo/issue_template/atomic_task.md`** — spec sources whitelist; extracted-context section (quote 5-30 lines per source so issue self-contained); do-not-read list; allowed-touched-paths whitelist; escape hatch; unknowns / owner questions. - **`.forgejo/issue_template/meta_decomposition.md`** — hard cap 5-10 children; produced children carry `proposed` / `needs-triage` / `not-ready` labels by default (NOT `ready-for-agent`); decomposing agent must post `spec sources read` disclosure on close. - **`.forgejo/issue_template/owner_decision.md`** — questions requiring piotr's input; `owner-attention` label auto-applied. Total: 5 files, +602 / -31 (initial commit + Oracle-driven amendments). ## Review focus (per Oracle review 2026-05-05) Please review this as a **governance/template PR**. Key questions: 1. Could an unfamiliar agent select work without reading the whole repo? (Test: simulate a cold-start agent reading only README → AGENTS.md §"Joining as a new agent" → an open atomic_task issue. Can they get to a first PR?) 2. Do the templates prevent oversized or ambiguous issues? (Test: try writing a vague issue using `atomic_task.md` template — do the required sections force concreteness?) 3. Is identity isolation clear enough? (Test: can a new agent identify their actor + retrieve PAT + verify push attribution from the cookbook alone?) 4. Are meta-decomposition tasks constrained enough to avoid backlog spam? (Test: hard cap 5-10 + label `proposed` default + decomposing agent ≠ implementer + spec-sources-read disclosure — would Antigravity produce 50 issues?) 5. Are non-goals explicit enough to prevent scope expansion? (`This PR does NOT` section above; `## Explicit out-of-scope` in templates; `Do NOT read` in atomic_task; escape hatch protocol.) ## Oracle review applied This PR went through Oracle (GPT-5.2 Thinking) review per AGENTS.md §"Oracle escalation discipline" criterion 2 (cross-cutting strategic decision; meta-architecture for swarm enablement). Oracle response in `.sisyphus/oracle-paste/swarm-strategy-2026-05-05.md`. Key insights applied in commit `2996a7d`: - Issues become **Context Packs**, not pointers — extracted/quoted context in templates - **Activation gating** via lifecycle labels prevents auto-generated issues from being pickable until human-reviewed - **Hard caps** (5-10 children/meta) prevent backlog spam - **Disclosure** (spec sources read) makes silent scope expansion auditable Oracle confirmed strategy C (hybrid: meta-decomposition skeleton + onboarding) is correct; structural guardrails were the missing piece. ## Spec sources read - `PLATFORM_CHARTER.md` — to understand identity-isolation references - `AGENTS.md` (pre-amendment) — to identify where cookbook insertion fits without redundancy - `decisions/0001-canary-mandatory-pm-cadence.md` §Rule 4 + ADR 0002 §Rule 2 — for size-class and iter-cap references in cookbook - `INDEX.md` — to confirm artifact map references in README - `README.md` (pre-rewrite, 24-line stub) — to understand what was lost vs. preserved - `.sisyphus/oracle-paste/swarm-strategy-2026-05-05.md` — Oracle output applied to amendments ## Known follow-up After merge: 1. Open ONE pilot meta-decomposition issue (target: L4 materialization, since plan §L4 has the most decomposable atomic candidates). 2. Have one agent decompose into 5-10 proposed atomic tasks. 3. Review quality of generated children before applying `ready-for-agent`. 4. Patch templates / cookbook based on what surfaces. 5. Then fan out: open additional meta-issues per remaining plan layer with `not-ready` label until pilot validates. ## Test plan - [ ] Operator readback: README §"I just walked in" feels correct as the entry point - [ ] Operator readback: AGENTS.md §"Joining as a new agent" 8-step flow is the right ordering - [ ] Operator readback: activation-gating discipline (proposed → ready-for-agent) feels right for guarding against Antigravity-style spam - [ ] Manual canary 3+3 fires + passes (or operator_override per Rule 2) - [ ] After merge: claude opens 1 pilot meta-issue (L4 materialization) using new `meta_decomposition.md` template - [ ] After merge: pilot meta-issue is decomposed by one agent into 5-10 `proposed` atomic issues - [ ] Reviewer applies `ready-for-agent` only after quality check - [ ] First swarm-pickable atomic issue produces a clean PR per the cookbook

claude added 1 commit

2026-05-05 00:04:36 +02:00

docs(repo): swarm-fundament — onboarding map + AGENTS amend + issue templates

canary-required / collect-diff (pull_request) Successful in 4s

Details

infra-docs-drift / docs-drift (pull_request) Successful in 3s

Details

canary-required / canary (pull_request) Failing after 1s

Details

443970af4c

Setup so a fresh agent (claude / codex / glm / antigravity / new arrival)
can pick up an issue cold and finish it without burning context on the
whole repo.

- README.md: rewrote as agent-entry-point with cold-start guide,
  mobile-scannable repo map, work-flow summary, identity-isolation TL;DR,
  quality-gates table, "where to put new memory" rules
- AGENTS.md: added "Joining as a new agent" 8-step cookbook (identity
  verify, pick issue, branch, read only spec sources, do work, open PR,
  fire canary, close loop) + "Issue conventions" section
- .forgejo/issue_template/: 3 templates — atomic_task.md (single PR
  scope), meta_decomposition.md (self-replicating spec for swarm; first
  agent only decomposes), owner_decision.md (questions requiring piotr's
  input)

Self-replicating principle: meta-issues spawn atomic issues; no single
agent burns context on a whole plan layer. Opens way for Antigravity
(Issue #57) and future swarm work.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

claude added 1 commit

2026-05-05 00:20:27 +02:00

docs(repo): apply Oracle review insights — Context Pack discipline + activation gating

canary-required / collect-diff (pull_request) Successful in 3s

Details

infra-docs-drift / docs-drift (pull_request) Successful in 4s

Details

canary-required / canary (pull_request) Failing after 1s

Details

2996a7dff4

Per Oracle review 2026-05-05 (.sisyphus/oracle-paste/swarm-strategy-2026-05-05.md):

- atomic_task template: spec sources are now an explicit WHITELIST; added
  Extracted context section (quote 5-30 lines from each source so issue
  is self-contained for cold pickup); Do NOT read section names adjacent
  but out-of-scope files; Allowed touched paths whitelist; Escape hatch
  protocol for premise-breaks; Unknowns / owner questions section
- meta_decomposition template: hard cap 5-10 child atomic issues; produced
  children carry `proposed` / `needs-triage` / `not-ready` labels by
  default (NOT `ready-for-agent`); decomposing agent must post spec
  sources read disclosure on meta-issue close
- AGENTS.md cookbook §Step 4: spec sources whitelist semantics; PR body
  must include `## Spec sources read` disclosure list (CI cannot enforce
  cognition; review enforces disclosure)
- AGENTS.md §Issue conventions: documented activation gating lifecycle
  labels + hard caps + self-replicating principle now requires human
  review before swarm pickup

Oracle's framing: self-replicating meta-issues are safe iff propagation is
*reviewed*, not automatic. This commit makes that gate explicit in the
templates and cookbook.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

claude referenced this pull request

2026-05-05 00:22:46 +02:00

[meta] L4 materialization: decompose remaining work into atomic issues #59