Codify operational learnings: memory, skills, ops bots, branching/verify/worktrees guides#3
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d625581eb3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## Scope this run | ||
|
|
||
| - Commits on the integration branch since the last review point. The "last review point" is the head SHA of the most recent issue this routine produced (read from the issue body's frontmatter); on the first run, use `HEAD~24h`. |
There was a problem hiding this comment.
HEAD~24h fallback revision
On a first run (no prior review issue), this fallback makes the commit-range query fail because HEAD~24h is not a valid Git revision spec (~ expects a parent-count, not a time duration). In practice, commands like git log --oneline HEAD~24h..HEAD error out immediately, so the bot cannot establish scope and produces no review. Use a time-based filter (for example --since) or a valid commit ancestor fallback.
Useful? React with 👍 / 👎.
| Per‑project, before the first scheduled run: | ||
|
|
||
| 1. Create the `review-bot` label. | ||
| 2. (Optional) Add the `review-fix-shipped` GitHub Action that auto‑flips checklist items on merge. A starter is in [`.github/workflows/`](../../../.github/workflows/) — adopt as needed. |
There was a problem hiding this comment.
This setup step claims there is a starter workflow under .github/workflows/, but that path does not exist in the repository, so operators following the checklist hit a dead end when enabling auto-flip. Because this is part of the required preflight setup for review-bot, the missing reference blocks or delays a correct deployment path.
Useful? React with 👍 / 👎.
…rter pointer Addresses two Codex P1/P2 findings on PR #3. P1: HEAD~24h is not a valid Git revision — `~` is a parent-count operator, not a duration. On the first run (no prior review issue) the fallback would error immediately. Switch to `git log --since='24 hours ago'` and call out the trap explicitly so the prompt cannot regress. P2: The setup checklist pointed operators to a "starter" GitHub Action under `.github/workflows/` that does not exist in this template. The auto-flip contract is documented in the PROMPT itself; the workflow implementation is project-specific. Reword the step to make that explicit and remove the dead link.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7de710308b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## How to apply | ||
|
|
||
| - Before any non‑trivial change: `git switch <integration-branch> && git pull --ff-only && git switch -c <slug>`. |
There was a problem hiding this comment.
The branch-creation command here uses git switch -c <slug>, which creates unprefixed branch names that conflict with this template’s own branch policy (feat/*, fix/*, etc.) and default push allowlist in .claude/settings.json (git push ... feat/*|fix/*|...). In agent runs that enforce those permissions, following this instruction leads to a push denial until the branch is renamed, so the documented happy path is broken.
Useful? React with 👍 / 👎.
|
|
||
| - Every roadmap row in the plan contains a closed‑state token (`[x]`, `shipped`, `complete`, `superseded`, `closed`). | ||
| - The plan's last commit on the integration branch is **≥14 days old**. (The quiet period catches in‑flight follow‑ups.) | ||
| - Any tracker issue linked from the plan is closed or carries a terminal label (`completed`, `wontfix`, `superseded`). |
There was a problem hiding this comment.
This criterion allows archiving when a tracker issue is still open but has a terminal label, which contradicts the later hard rule in the same prompt that says to never archive while the tracker issue is open. That conflict makes the bot’s decision policy ambiguous and can archive plans before the tracker is actually closed, depending on which instruction the model follows.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1e272235d6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ## Output | ||
|
|
||
| - **Primary sink:** one issue per run, labelled `review-bot`. | ||
| - **Secondary sink (optional):** a committed Markdown digest at `docs/daily-reviews/YYYY-MM-DD.md` with the same body, opened as a tiny PR. Useful for repos that want a searchable archive; skippable if not. |
There was a problem hiding this comment.
The prompt gives mutually exclusive instructions: it declares the routine read-only and says it must never open PRs, but this output line tells it to commit a digest and open a PR. In practice, implementations will either ignore the optional digest feature or violate the hard rules, so operators cannot rely on consistent behavior for review-bot runs.
Useful? React with 👍 / 👎.
| - `Divergent action pins: <owner>/<repo>` (one per divergent action; non‑aborting). | ||
| - `Unresolved action pins YYYY-MM-DD` (one per run grouping `no-releases` / `unresolved` rows; non‑aborting). | ||
| - `Action SHA bumps YYYY-MM-DD — <sha7>` (actionlint or verify failure after applying bumps). | ||
| - **No‑op runs leave no trace** when the scanner exits 0 *and* zero `no-releases`/`unresolved` rows exist. |
There was a problem hiding this comment.
This no-op condition allows a silent run when there are no no-releases/unresolved rows, but the same prompt also says major bumps are not auto-applied and must be left for owner approval. If a scan contains only major PENDING bumps, the routine can exit with no PR and no issue, so required owner action is never surfaced and majors can be missed indefinitely.
Useful? React with 👍 / 👎.
|
|
||
| ## Relationship to `docs-review-bot` | ||
|
|
||
| `docs-review-bot` audits `docs/` for drift (see its [`PROMPT.md`](../../agents/operational/docs-review-bot/PROMPT.md)). This directory is **excluded** from that audit by default — old reviews are expected to be stale relative to current code; that's their whole purpose. |
There was a problem hiding this comment.
This sentence says docs/daily-reviews/ is excluded from docs-review-bot by default, but docs-review-bot’s scope includes docs/ and only hard-excludes docs/archive/ plus its own files. Teams enabling daily digests will therefore get stale-digest drift findings despite being told that cannot happen, which creates avoidable noise and setup confusion.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2662f79d82
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ```bash | ||
| # Create | ||
| git worktree add .worktrees/<slug> -b <slug> origin/<integration-branch> |
There was a problem hiding this comment.
This command creates unprefixed branches (<slug>), but the repository’s own branching policy and default push allowlist require prefixed names (feat/*, fix/*, etc.). Following this instruction in a default setup causes pushes from these worktrees to be denied until the branch is renamed, so the documented workflow fails for normal users.
Useful? React with 👍 / 👎.
| ## Process | ||
|
|
||
| 1. **Pre‑flight:** if the scanner reports any `ERROR` row, abort the run and open a failure issue (auth, network, rate‑limit). `DIVERGENT`, `no-releases`, and `unresolved` rows do **not** abort — they file separate triage issues but processing of `PENDING` rows continues. | ||
| 2. **Idempotency check:** if any open `chore/actions-bump-*` PR already exists from this routine's login, exit silently. Older un‑merged bump PRs must block new ones to avoid stacking. |
There was a problem hiding this comment.
The run exits immediately when any prior chore/actions-bump-* PR is open, which skips the major-version escalation path entirely for that run. Fresh evidence here is that Process step 2 short-circuits before the prompt’s own hard rule that major bumps must be surfaced every run they remain pending, so newly discovered majors can stay invisible while an older bump PR is still open.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 557e2b2e73
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## Scope this run | ||
|
|
||
| - All open dependency‑update PRs in the repo whose body shape matches Dependabot / Renovate / equivalent. PRs without the recognised body shape are skipped (they are not dep PRs even if their branch name looks like one). |
There was a problem hiding this comment.
The scope currently accepts any open PR whose body shape looks like Dependabot/Renovate, which means a spoofed PR can be treated as trusted dependency automation. In repositories that accept external or broad internal PR creation, this allows attacker-controlled code to reach step 4 (install deps + verify) on a privileged scheduled runner, and then enter the auto-merge decision path; this is a concrete credential-exposure and unsafe-merge risk. Gate candidates by trusted author/app identity (for example exact bot login/app IDs) in addition to body format, and fail closed when identity cannot be verified.
Useful? React with 👍 / 👎.
| Plans are Markdown. Instead of running the full verify gate, the routine performs three lightweight checks before opening the PR: | ||
|
|
||
| 1. **Markdown format check** — the project's Markdown formatter in check mode (e.g. `prettier --check 'docs/**/*.md'`, `mdformat --check docs/`). Skip the build / test / typecheck stages. | ||
| 2. **Local‑link integrity** — every relative Markdown link inside the moved files still resolves after the `git mv`. (A plan moving from `docs/plans/foo.md` to `docs/archive/plans/foo.md` keeps relative paths under `docs/` intact, but cross‑references *into* the moved file from elsewhere need a quick scan.) |
There was a problem hiding this comment.
This line assumes moving docs/plans/<file> to docs/archive/plans/<file> preserves relative links under docs/, but the extra directory depth changes relative-path resolution. Combined with this prompt’s hard rule that plan bodies cannot be edited beyond the archive banner, plans containing relative links will systematically fail the local-link check and become unarchivable. Update the policy to either rewrite links during archival or exempt archived snapshots from strict in-file relative-link validation.
Useful? React with 👍 / 👎.
…lls + bots Adds the operational layer that complements the lifecycle workflow from PR #1, distilled from patterns observed in the agentonomous repo. - .claude/memory/ — operational memory split from durable principles in memory/constitution.md. README + MEMORY.md index + 8 feedback_*.md rules (pr_hygiene, verify_gate, worktrees_required, pr_workflow, docs_with_pr, parallel_pr_conflicts, autonomous_merge, memory_edits). - .claude/skills/ — reusable how-tos (verify, new-adr, review-fix) any agent can invoke. Skills don't override agent tool restrictions. - .claude/settings.json — permission baseline: allow git ops on topic branches, deny push to main/develop, deny --no-verify, deny rm -rf on protected paths. SessionStart hook surfaces the memory index. - agents/operational/ — second class of agent: always-on, scheduled routines that act against the live repo. PROMPT.md + README.md per bot. Five seeded: review-bot, docs-review-bot, plan-recon-bot, dep-triage-bot, actions-bump-bot. - .gitignore — add .worktrees/ and .claude/cache/.
…, CONTRIBUTING Complements the operational layer (memory + skills + bots) with the generalised guides those layers reference, and stitches the new pieces into the root pointers. - docs/branching.md — two supported shapes (main-only; develop+main+demo), topic-branch prefixes, integration-branch rules. - docs/worktrees.md — .worktrees/<slug>/ pattern, lifecycle, pitfalls. - docs/verify-gate.md — the single-command pre-PR contract every project using this template implements (npm/make/just/cargo all welcome). - docs/plans/README.md — YYYY-MM-DD-<slug>.md naming, lifecycle, relationship to specs/<feature>/. - docs/archive/README.md — read-only-by-convention archive for completed plans / superseded specs; preserves git history via git mv. - CONTRIBUTING.md — contributor guide for evolving the template itself, using its own workflow. - AGENTS.md — adds operational-memory + verify/branching/worktrees rules, documents the two classes of agent, links the new files. - CLAUDE.md — imports .claude/memory/MEMORY.md alongside the constitution; adds notes on skills, operational bots, settings.json, and worktrees. - README.md — file map now includes .claude/memory, .claude/skills, .claude/settings.json, agents/operational/, the three new docs/ guides, docs/plans, docs/archive, CONTRIBUTING.md; new "Two classes of agent" section.
…rter pointer Addresses two Codex P1/P2 findings on PR #3. P1: HEAD~24h is not a valid Git revision — `~` is a parent-count operator, not a duration. On the first run (no prior review issue) the fallback would error immediately. Switch to `git log --since='24 hours ago'` and call out the trap explicitly so the prompt cannot regress. P2: The setup checklist pointed operators to a "starter" GitHub Action under `.github/workflows/` that does not exist in this template. The auto-flip contract is documented in the PROMPT itself; the workflow implementation is project-specific. Reword the step to make that explicit and remove the dead link.
…dit gaps
Synthesized fix for the parallel review (Codex bot + three internal
review subagents). Addresses ~20 distinct findings in one commit so the
contradictions are resolved coherently rather than piecemeal.
Codex P2 findings (this commit):
- feedback_pr_hygiene.md: branch-creation example missing prefix; the
unprefixed branch would be denied at push time by settings.json
allowlist. Now: `git switch -c <prefix>/<slug>` with prefix list and
link to docs/branching.md.
- plan-recon-bot/PROMPT.md: archive-criterion "issue closed OR has a
terminal label" contradicted the hard rule "never archive while issue
open". Tightened to "issue is closed", terminal-label exception
removed.
Constitutional / structural:
- docs/adr/0004 — adopts operational agents as a second class under
Articles VI/VII/IX. Was missing — operational bots are a new role
class and the constitution requires an ADR for that. Indexed in
docs/adr/README.md.
Cross-file contradictions:
- feedback_memory_edits.md vs feedback_docs_with_pr.md: rewrote the
former into Case A (standalone memory edit) + Case B (memory rides
with the code PR that introduced the convention). The two files no
longer contradict.
- review-fix SKILL.md vs review-bot PROMPT.md: magic line was
`Refs <name> finding:<id>` (two spaces, no `#`) in the skill but
`Refs #<num> finding:<sha7>.<idx>` in the bot. Aligned to the bot's
format and made the precise format mandatory in the skill.
- dep-triage-bot table vs narrative: table said runtime patches
"approval comment, owner merges"; narrative said "comment-and-merge
(or comment-only for runtime)". Realigned to never auto-merge runtime
bumps regardless of verify status. Auto-merge now requires a
permissive cell *plus* the four gates from feedback_autonomous_merge.
Eight-section shape:
- dep-triage-bot/PROMPT.md: was missing `Scope this run` and renamed
`Process` to `Process per PR`. Restored both per the canonical
shape declared in agents/operational/README.md (which is now also
explicit that sub-headings are fine but parent must be `## Process`).
Plan-recon-bot:
- Replaced "run the verify gate" on a docs-only PR (wasteful + likely
to fail in projects whose build needs source) with a docs-only check
(Markdown format check + local-link integrity + git status clean).
- Failure recovery moved to the main checkout — `git branch -D` from
inside the worktree being deleted is impossible. Now: switch to main
checkout first, then remove the worktree, then delete the branch.
- Idempotency now uses ROUTINE_GH_LOGIN per the canonical auth
contract in agents/operational/README.md.
- One-commit-per-move + revert-on-failure inconsistency resolved: the
failed move alone is dropped (file as flag); earlier successful
per-move commits stay.
Settings.json bypass surface:
- Removed `Bash(git checkout:*)` and `Bash(git reset:*)` from allow —
too broad (allowed `git reset --hard origin/main`).
- Added denies for `git commit -n`, `git push -n` (short-flag aliases
of --no-verify), `git -c core.hooksPath=` (config bypass),
`HUSKY=` / `HUSKY_SKIP_HOOKS=` env bypass, `git reset --hard
origin/{main,develop}`, `git checkout {main,develop}`,
`git branch -d {main,develop}`, `git push --force` / `--force-with-lease`
/ `-f` to any branch.
- Schema URL canonicalised to www.schemastore.org.
Skills:
- .claude/skills/README.md now lists tool requirements per skill so the
9 lifecycle agents without Bash know which skills they cannot invoke.
Severity + auth contracts:
- agents/operational/README.md now defines a single canonical severity
scale and a GH_TOKEN/ROUTINE_GH_LOGIN auth contract referenced from
every bot.
- review-bot and docs-review-bot now point to the canonical scale
rather than redefining it.
Scaffolding:
- docs/daily-reviews/README.md — review-bot's optional secondary sink.
- docs/archive/plans/.gitkeep — make the directory plan-recon-bot
archives into actually exist.
- review-bot/README.md now points to docs/daily-reviews/README.md.
Other:
- docs/verify-gate.md: corrected the Rust example — Cargo has no built-in
alias mechanism; `cargo verify` would not work as written.
- CLAUDE.md: added `/spec:start` to the slash-command list (was
referenced from CONTRIBUTING.md but missing here).
review-bot (PROMPT.md:49 + README.md): Hard rule said "Never open a PR" while Output offered an optional digest PR — mutually exclusive. Resolved by removing the digest sink entirely. The bot is now purely read-only: one GitHub issue per run, no PRs, no commits, no edits. The Markdown-archive pattern is now framed as project-implemented (separate scheduled job or by hand) in docs/daily-reviews/README.md. actions-bump-bot (PROMPT.md:52): No-op condition allowed silent runs whose only PENDING rows were majors — owners would never see them. Added a fifth issue category `Major action bump pending: <owner>/<repo> <old> → <new>`, filed every run a major remains pending (with title-search dedup to avoid duplicates). Tightened the no-op condition to also require zero pending majors. Updated the Hard rule to match. docs-review-bot (PROMPT.md): daily-reviews/README.md claimed `docs/daily-reviews/` was excluded from docs-review-bot but the bot's exclusion list only covered docs/archive/. Made the claim true: added docs/daily-reviews/ to the bot's hard exclusions. Daily review digests are SHA-anchored snapshots that are expected to go stale; flagging drift in them is noise. Also updated agents/operational/README.md table row for review-bot to reflect the read-only output (removed "+ daily markdown digest").
feedback_worktrees_required.md (line 24): Worktree-creation example used `-b <slug>` — unprefixed branch name that the default settings.json allowlist would deny at push time (same class as the earlier feedback_pr_hygiene.md fix). Fixed to `-b <prefix>/<slug>` and called out that the path is unconstrained but the branch name must satisfy the allowlist. actions-bump-bot/PROMPT.md (line 26): Process step 2 (idempotency exit on prior open chore/actions-bump-* PR) short-circuited the whole run — including the major-bump escalation issues that the hard rule says must be filed every run a major remains pending. Reordered the process so issue filing (majors / divergent / unresolved) runs FIRST and is independent of the prior-PR check. The prior-PR check now only gates bump-PR creation, not escalation issues. Idempotency section split into two named gates so the scopes are explicit.
…recon link rot (P2)
dep-triage-bot/PROMPT.md (P1, line 17):
Scope was "any PR whose body shape matches Dependabot/Renovate" —
body shape is spoofable, so a malicious PR mimicking the format would
be installed and verified on the routine's privileged runner, then
walked through the auto-merge decision path. Concrete credential
exposure + supply-chain risk.
Fixed by adding a mandatory author-identity allowlist:
- New env var TRUSTED_DEP_BOT_LOGINS (comma-separated, exact match
on author.login, plus require author.type == "Bot").
- Fail-closed: unset means "process zero PRs and exit with a setup
error", never "process every PR".
- Process step 1 is now the identity check; rejected PRs never reach
install-deps / verify.
- Hard rules updated: never install/verify against an untrusted
author; identity is the trust boundary, body shape is secondary.
- README setup checklist + agents/operational/README.md auth contract
both updated.
plan-recon-bot/PROMPT.md (P2, line 51):
The "Local-link integrity" check was impossible to satisfy. Moving
docs/plans/foo.md → docs/archive/plans/foo.md adds a directory level,
so any relative link (`../steering/quality.md`) inside the moved file
no longer resolves. Combined with the hard rule "Never edit plan
bodies beyond the banner", any plan with relative links was
unarchivable.
Fixed by:
- Removing the in-file link-integrity check entirely.
- Adding a new section "Archived plans are snapshots" that codifies
the principle: archived plans are read-only historical records;
link rot is the natural state.
- Replacing the dropped check with an *informational* incoming-
reference scan (files outside docs/archive/plans/ that still link
to the moved plan's old path) — surfaces in the PR body as
follow-up for the owner; does NOT block the archive.
- Updated PR body shape to reflect 2 blocking checks + 1 informational
section.
Luis85
force-pushed
the
claude/integrate-agentonomous-learnings-OiaaP
branch
from
a2a4de5 to
316b07f
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 316b07f61a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "Bash(git push --no-verify:*)", | ||
| "Bash(git push -n:*)", | ||
| "Bash(git commit --no-verify:*)", | ||
| "Bash(git commit -n:*)", |
There was a problem hiding this comment.
The settings comment says command rules are prefix-matched, but these deny patterns only catch --no-verify when it appears immediately after git push/git commit; with broad allows like Bash(git commit:*) and Bash(git push origin feat/*), a command such as git commit -m "x" --no-verify (or git push origin feat/foo --no-verify) bypasses the intended hook enforcement. git push -h also confirms --no-verify is a valid push option, so this is a practical bypass of the documented hard rule.
Useful? React with 👍 / 👎.
| "Bash(git push -u origin refactor/*)", | ||
| "Bash(git push -u origin chore/*)", | ||
| "Bash(git push -u origin docs/*)", | ||
| "Bash(git push origin feat/*)", |
There was a problem hiding this comment.
Because push permissions are prefix-based, allowing git push origin feat/* also allows refspecs like git push origin feat/my-branch:main, which push to the protected integration branch while still matching the allowed prefix. The deny rules only target commands starting with git push ... main, so this route can bypass the stated “no direct push to main/develop” safeguard.
Useful? React with 👍 / 👎.
Adds a mattpocock-style skills layer on top of the v0.1 Spec Kit foundation, integrated cleanly with PR #3's operational learnings (.claude/memory, .claude/settings.json, agents/operational/, docs/branching|verify-gate|worktrees.md). Skills (.claude/skills/): - orchestrate — natural-language entry to the 11-stage workflow. Reads workflow-state.md, gates with AskUserQuestion, dispatches /spec:* commands per stage. Lean depth writes idea/research stubs marked complete; Spike marks stages 3–10 skipped (none dispatched); per-stage Skip allowed only for stage 10. Crash-safe resume protocol against the canonical YAML artifacts: map. (SKILL.md + PHASES.md + RESUME.md, progressive disclosure pattern.) - grill — one-question-at-a-time interview primitive (after Pocock). - design-twice — parallel divergent design via Task tool (Ousterhout). /spec:design now reads the design-comparison.md synthesis as input. - tracer-bullet — vertical-slice planning for /spec:tasks. - tdd-cycle — strict red/green/refactor scoped to one /spec:implement task; canonical task-ID commit format for traceability. - record-decision — wraps /adr:new with ADR-worthiness criteria. ADR bodies immutable from creation; only YAML status and supersession pointers may change. - domain-context — lazy maintenance of docs/CONTEXT.md (or multi-context layout); subagent-safe via [CONTEXT-CONFIRM] flag. - ubiquitous-language — lazy maintenance of docs/UBIQUITOUS_LANGUAGE.md. Sink catalog (docs/sink.md): one source-of-truth document for every markdown artifact — workflow-scoped (specs/<slug>/*.md), cross-cutting (docs/adr/, docs/CONTEXT.md, docs/UBIQUITOUS_LANGUAGE.md), governance, and tooling. Documents ownership, eager vs. lazy, immutability, naming, and read order for stage subagents. v0.1 command updates (precondition rigor, integrating with PR #3): - /spec:design now reads design-comparison.md from design-twice and passes it to all three design subagents as input context. - /spec:release verdict check now explicitly accepts both Approved and Approved with conditions (per templates/review-template.md). - /spec:* preconditions reaffirm `complete`-only upstream and cite the agents that depend on the content (Lean stubs satisfy this; Spike never dispatches against skipped artifacts). Skills README, root README, and CLAUDE.md updated to surface the combined catalog (workflow conductor + practice skills + cross-cutting sink + operational skills from PR #3) and bump version to v0.2. Iterated through ~10 rounds of Codex review (~26 comments addressed) plus self-reviews via parallel subagents (schema, slash-command preconditions, subagent contracts, cross-skill consistency, scenario walkthrough). https://claude.ai/code/session_01PTc1UHovmBA1Psbd3719KD
Adds a mattpocock-style skills layer integrated cleanly with PR #1's foundation and PR #3's operational learnings. Skills (.claude/skills/): - orchestrate — natural-language entry to the 11-stage workflow. Reads workflow-state.md, gates with AskUserQuestion, dispatches /spec:* commands per stage. Lean depth writes idea/research stubs marked complete; Spike marks stages 3–10 skipped (none dispatched); per-stage Skip allowed only for stage 10. Crash-safe resume protocol against the canonical YAML artifacts: map. - grill — one-question-at-a-time interview primitive (after Pocock). - design-twice — parallel divergent design via Task tool (Ousterhout). /spec:design now reads the design-comparison.md synthesis as input. - tracer-bullet — vertical-slice planning for /spec:tasks. - tdd-cycle — strict red/green/refactor scoped to one /spec:implement task; canonical task-ID commit format for traceability. - record-decision — wraps /adr:new with ADR-worthiness criteria. ADR bodies immutable from creation; only YAML status and supersession pointers may change. - domain-context — lazy maintenance of docs/CONTEXT.md (or multi-context layout); subagent-safe via [CONTEXT-CONFIRM] flag pattern. - ubiquitous-language — lazy maintenance of docs/UBIQUITOUS_LANGUAGE.md. Sink catalog (docs/sink.md): one source-of-truth document for every markdown artifact — workflow-scoped (specs/<slug>/*.md), cross-cutting (docs/adr/, docs/CONTEXT.md, docs/UBIQUITOUS_LANGUAGE.md), governance, and tooling. Ownership, eager vs. lazy, immutability, naming, read order. v0.1 command updates: /spec:design now reads design-comparison.md from design-twice; /spec:release verdict check accepts Approved | Approved with conditions; /spec:* preconditions reaffirm `complete`-only upstream and cite the agents that depend on the content. Skills README, root README, and CLAUDE.md updated to surface the combined catalog (workflow conductor + practice skills + cross-cutting sink + operational skills from PR #3) and bump version to v0.2. Iterated through ~10 rounds of Codex review (~26 comments addressed) plus parallel-subagent self-reviews (schema, slash-command preconditions, subagent contracts, cross-skill consistency, scenario walkthrough).
(P1 #1) Workflow permissions check now scans `jobs.<job>.permissions` too, not only the workflow-level block. GitHub Actions applies job-level permissions after workflow-level, so a compliant top-level can be widened by a job override (e.g. `actions: write`). Each declared block — top-level or per-job — must be subset+match against the least-privilege set. Top-level still requires presence; job-level blocks are optional but if present must not widen scope. (P1 #2) `package.json#files` is now enforced against the contract include list. Added `EXPECTED_PACKAGE_FILES` derived from `package-contract.md` §3 and plumbed it through the readiness call as the default expectation. Required shipping paths can no longer be removed without triggering a PkgFiles diagnostic. (P1 #3) `realGit().resolveRef` now peels annotated tags via `^{commit}` so `git rev-parse` returns the commit SHA on both sides of the tag-at-main comparison. Without peeling, an annotated `vX.Y.Z` tag (created via `git tag -a`) returned the tag-object SHA while `main` returned a commit SHA, falsely reporting TAG_NOT_AT_MAIN. The `^{commit}` suffix is a no-op for refs already pointing at a commit (lightweight tags, branches, raw SHAs). Documented the invariant on the `GitInterface` contract. (P2) Release-notes shape check now validates `changelog.exclude.labels` and `changelog.exclude.authors` are arrays. Previously `exclude: {}` passed because only the block's existence was checked, missing the T-V05-003 contract requirement to filter maintenance and bot entries. Tests cover all four fixes (Scenarios 4d, 5d, 5e, 3c plus the existing regression suite). 26 tests pass; full suite green; `npm run verify` ok. Tightened `ExpectedPackage.files` and `expectedPackageFiles` types to `readonly string[]` so the const list satisfies the typecheck. Findings: PR #158 inline comments by chatgpt-codex-connector on commit 13a657d. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… truth Three new Codex P1s on commit 05d84a9, all real internal-consistency drift between agents/skills/commands and the shared goal-state schema. Fix together so the documented happy paths run end-to-end. current_phase drift (P1 #1): `set-goal` initialises `current_phase: scope` per the shared schema (`scope | observe | orient | decide | act | review | closed`), but several files referenced a non-existent `goal` value or a stale list that excluded `scope`: - /goal:observe accepted `goal | review | observe` — would fail preflight on a freshly signed goal. Now: `scope | review | observe`. - /goal:start said new goals get `current_phase: goal`. Now: `scope`. - /goal:close said amend re-entry sets `current_phase: goal`. Now: `scope` (matching the post-`set-goal` entry state). act_approval drift (P1 #2): The actor, decider, orchestrator, and the Codex iteration workflow all referenced an `act_approval` entry in `goal-state.md`. The shared schema does not define that field. The canonical record of approval lives in the `## Human Approval` section of the decision set in `decisions.md`, which is filled by the `decide` skill at the act gate. - agents/actor.md — pre-flight now reads the Human Approval section of decisions.md as the canonical source, with the orchestrator's `## History` row as the secondary signal that the gate cleared. - agents/goal-orchestrator.md — clarified that Decide owns the Human Approval section; orchestrator appends an act-gate row to `## History` citing the approved decision-set id. - agents/decider.md — clarified the decider does not write the Human Approval section itself; the `decide` skill captures the user's verdict there, then the orchestrator records the `## History` row. - .codex/workflows/goal-iteration.md — same alignment for the Codex side; the Safety rail now references the Human Approval section. Review preflight drift (P1 #3): /goal:review required an `actions/` artifact for every iteration, but the `decide` skill explicitly advances `current_phase: review` with no actions when the act gate produces nothing executable (all rejected, deferred, or `act_gate: never`). That left no-action iterations unable to close. Now /goal:review accepts both: - the post-Act case (actions/ artifact present, the normal path) - the no-action case (`## History` records an `act: skipped` row with reason — `all rejected` / `deferred` / `policy forbids`) `npm run verify` is green locally. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
…dit + per-command frontmatter check Three P1 items from the wave-9 punch list land together: P1 #1 — README install recipe (README.md §Install): Four concrete install paths replace the prior "copy the folder" wording: (a) Claude Code marketplace (canonical when published), (b) `git subtree` for upstream-tracking adopters, (c) `git submodule` for pinned vendoring, (d) one-shot `cp -r` for fork-and-own. Decision rule appended below the recipes to help adopters pick. The existing `Adopt the entry points` step is preserved. P1 #2 — Required-field enforcement audit (skills/decide/SKILL.md Step 3a): The H-1 research recommendation made `rationale`, `confidence`, `reversible: Y|N` required on every decision proposal. The decider agent §Validation enforces this at first-pass (drops malformed proposals to `## Alternatives Considered`). The skill now enforces at second-pass before opening the act gate: rejects the whole set if any proposal still lacks a required field, surfaces an explicit AskUserQuestion with three options (re-dispatch / drop the malformed / accept-with-acknowledgement). No duplicated enforcement; clean first-pass / second-pass division. P1 #3 — Per-command frontmatter ↔ table consistency check (scripts/check-roster.sh check_8 + automation-spec.md §B2 + scripts/README.md): The §B2 deferral noted in earlier waves is now closed. check_8_command_descriptions extracts each command file's frontmatter `description:` and the corresponding row from commands/goal/README.md's `## Commands` table, then confirms they share at least one substantive keyword (with a stop-word filter for Goal-Loop boilerplate). All 15 /goal:* commands report OK on the current tree — no drift surfaced. automation-spec §B2 status annotation drops the deferral note ("implemented — all surfaces covered"); scripts/README table row enumerates all 8 covered surfaces. `bash scripts/check-all.sh`: all 7 checks pass; check_8 inside check-roster confirms 15/15 commands match their table descriptions. `npm run check:links` and typos clean. https://claude.ai/code/session_01CxFjqxucdBwScjAkMxU83s
2 participants
Summary
Adds the operational layer that complements the lifecycle workflow from #1, distilled and generalised from patterns observed in the agentonomous repo (
developbranch). Stacked on top of #1 — once #1 merges, this PR's diff will show only the additions below.The lifecycle workflow in #1 answers "how do we build one feature?". This PR answers "how do we work day‑to‑day in a repo where multiple agents and humans run in parallel, with always‑on routines watching for drift?"
What's added (36 new files, ~1,800 lines)
.claude/memory/— operational memoryDistinct from
memory/constitution.md(durable principles): the constitution is the law, this is the rolling record of how‑we‑work and current‑state. Mirrors the agentonomous pattern 1:1.README.md— what belongs here, what doesn't, how to update.MEMORY.md— short index agents read at session start; both axes (Project state, Workflow rules).feedback_*.mdrules generalised from observed behaviour:pr_hygiene,verify_gate,worktrees_required,pr_workflow,docs_with_pr,parallel_pr_conflicts,autonomous_merge,memory_edits..claude/skills/— reusable how‑tosThird dimension alongside agents (who) and commands (what's the next stage); skills answer how recurring procedures are always done. Skills never override an agent's tool restrictions.
verify/SKILL.md— run the project's pre‑PR gate, report pass/fail actionably.new-adr/SKILL.md— scaffold an ADR with the next free number, immutability‑safe.review-fix/SKILL.md— turn a review finding into an isolated worktree + plan, single & sweep modes..claude/settings.json— permission baseline + hookgit status/diff/log/show/branch/switch/checkout/fetch/pull --ff-only/add/restore/reset/commit/worktree, push tofeat/*,fix/*,refactor/*,chore/*,docs/*,claude/*.mainanddevelop(force or otherwise),--no-verify,rm -rf /,rm -rf .git,rm -rf srcand other protected paths.SessionStartsurfaces the memory index location.agents/operational/— five always‑on botsSecond class of agent, separate from lifecycle agents. Each =
PROMPT.md+README.md. All conservative, idempotent, and silent on quiet days.review-bot/— daily adversarial code review on the integration branch; one issue per run with stable finding IDs (<sha7>.<idx>).docs-review-bot/— weekly drift audit of in‑repo Markdown vs. current code state; read‑only.plan-recon-bot/— weekly archival of completed plans fromdocs/plans/todocs/archive/plans/viagit mv; one PR per run.dep-triage-bot/— auto‑merge safe Dependabot/Renovate bumps; flag risky ones; verify is the only signal that gates auto‑merge.actions-bump-bot/— weekly PR bumping pinneduses:SHAs in.github/workflows/; never crosses a major.The five share an eight‑section common shape (Role / Scope / Process / Hard rules / Output / Idempotency / Failure handling / Dry‑run mode) so reviewers can scan them quickly.
docs/— three generalised guides + plans/archive conventionbranching.md— two supported shapes (main‑only;develop+main+demo), topic prefixes, integration‑branch rules.worktrees.md—.worktrees/<slug>/lifecycle, why, pitfalls, when to skip.verify-gate.md— single‑command pre‑PR contract any project implements (Node/Python/Go/Rust examples).plans/README.md—YYYY-MM-DD-<slug>.mdnaming, when to use plans vsspecs/<feature>/.archive/README.md— read‑only‑by‑convention archive, preserves history viagit mv.Root pointers
CONTRIBUTING.md— contributor guide for evolving the template using its own workflow.README.md— file map updated, new "Two classes of agent" section.CLAUDE.md— imports.claude/memory/MEMORY.md, notes skills + bots + settings + worktrees.AGENTS.md— adds the operational‑memory pointer, branching/verify/worktree rules, "Two classes of agent" section..gitignore— adds.worktrees/and.claude/cache/.Why generalise rather than copy
The agentonomous prompts are highly specific (npm + Vite + Vitest + a custom
scripts/bump-actions.mjs). The patterns underneath them are language‑agnostic: SHA‑pinned actions, plan archival, dep triage, doc drift. Each bot here strips the implementation specifics and keeps the contract — which makes the template adoptable in a Python or Go repo without rewriting the whole prompt.Stacking on #1
This PR's base is
claude/spec-kit-foundation-h0Faq, notmain. Once #1 merges:main(or merge as‑is — GitHub will fast‑forward correctly).If you'd prefer to wait for #1 to merge first and rebase, say the word and I'll redo the base.
Tradeoffs / what I deliberately didn't do
scripts/bump-actions.mjs. Implementation is project‑specific; the prompt documents the contract any scanner must meet. Add a starter when this template gains a worked example..github/workflows/. The bots assume a scheduler, but the template stays scheduler‑agnostic for now (GitHub Actions, external cron, manual trigger all valid).memory/constitution.mdis durable principles;.claude/memory/is operational memory. Two files saying the same thing is the worst outcome — they don't overlap.README.mdmakes that clear: adopt one at a time, after lifecycle is in routine use.Test plan
README.md— file map matches the actual layout..claude/memory/MEMORY.mdand click through to onefeedback_*.md— does the rule read clearly without project‑specific context?agents/operational/review-bot/PROMPT.md) — does the eight‑section shape make it easy to grasp the routine?python3 -c "import json; json.load(open('.claude/settings.json'))"— JSON is valid (verified; included for the human reviewer to re‑check).git grep "memory/constitution.md"andgit grep ".claude/memory"— references in the new docs all resolve.README.mdshould make the answer obvious.https://claude.ai/code/session_01QW9qH8W4EyAgRHxrtXy5Ag
Generated by Claude Code