Merge branch 'worktree-os-sdlc' (os-sdlc concept map + to-tickets rename)
# Conflicts: # plugins/os-backlog/skills/route/SKILL.md
This commit is contained in:
jared
commit
06fff77d75
|
|
@ -113,7 +113,7 @@ next signal is production IRL session audits.
|
|||
|
||||
## Issue tracking
|
||||
|
||||
Issues (created via `/to-issues`) live on self-hosted Forgejo (`jared/cc-os`), queried with
|
||||
Issues (created via `/to-tickets`) live on self-hosted Forgejo (`jared/cc-os`), queried with
|
||||
the `tea` CLI — not GitHub/`gh`. See `docs/issue-workflow.md`.
|
||||
|
||||
## OpenSpec workflow
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ date: 2026-07-14
|
|||
status: Accepted
|
||||
supersedes:
|
||||
superseded-by:
|
||||
affected-paths: [plugins/os-sdlc/, docs/matt-pocock-skills-v1.1-notes.md]
|
||||
affected-paths: [plugins/os-sdlc/]
|
||||
affected-components: [os-sdlc, os-backlog, os-adr, os-vault]
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ entry is in the leaf file named.
|
|||
(ADR-0031) + three new prompt files; `/readonly` decided as plan-mode convention, no
|
||||
skill (ADR-0030); os-doc-hygiene `file_length` scanner signal shipped (issue #25 part 1);
|
||||
this file distilled to index+PD (issue #25 parts 2–3, ADR-0032). os-backlog slice 7
|
||||
shipped: SessionStart injection note + /to-issues tracker routing (issue #16); board-id
|
||||
shipped: SessionStart injection note + /to-tickets tracker routing (issue #16); board-id
|
||||
cache via BoardResolver (issue #22); slice 8 — Operations board + tracker-routing rubric
|
||||
category + ADR-0033 canonizing Planka-state/git-issues-spec (issue #17); route inspect
|
||||
issue-shape classification + split-by-kind default (issue #26); cross-project filing
|
||||
|
|
|
|||
|
|
@ -72,8 +72,8 @@ state and specs** (OpenSpec change `retire-planka-git-issues-only`).
|
|||
(`hooks/session_start.py` + `hooks/hooks.json`, os-adr-style plugin-local hook): WHEN→THEN
|
||||
rules for capture / routing / promotion / column ownership / autonomy labels, ADR-0029
|
||||
semantics (the issue body's "afk-ready → Review" was wrong — caught in Codex review),
|
||||
rules only, zero board state, ~447 tokens. `/to-issues` (global skill,
|
||||
`~/.agents/skills/to-issues/`) gained a destination-tracker step reading the
|
||||
rules only, zero board state, ~447 tokens. `to-issues` (now `to-tickets`; global skill,
|
||||
then at `~/.agents/skills/to-issues/`) gained a destination-tracker step reading the
|
||||
`.cc-os/config` tracker key; the `planka:`/unset default publishes slices as git issues
|
||||
on the repo remote + one Planka pointer card (spec/state boundary preserved — human gate
|
||||
decided 2026-07-13). `Backlog::Tracker.issues_destination` + 6 routing tests.
|
||||
|
|
@ -88,7 +88,7 @@ state and specs** (OpenSpec change `retire-planka-git-issues-only`).
|
|||
IRL audit (recurring)" (card `1818310715438531668`, P2 + semi, first progress comment
|
||||
`1818310889929966683`; recurrence contract: comment + move back to Backlog, never Done).
|
||||
Tracker-routing convention canonized as **ADR-0033** (Planka = state / git issues = specs,
|
||||
tracker key grammar, pointer + promotion rules; cites route/to-issues/session-start
|
||||
tracker key grammar, pointer + promotion rules; cites route/to-tickets/session-start
|
||||
rather than restating). os-context audit rubric gained category 8 `tracker-routing`
|
||||
(capture/route/promote compliance only). Bug found live and fixed: label color fallback
|
||||
only rescued `Planka::ValidationError`, but Planka rejects unknown colors as HTTP 400
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
# Issue workflow (Forgejo + tea)
|
||||
|
||||
_Last updated: 2026-06-30._
|
||||
_Last updated: 2026-07-16._
|
||||
|
||||
How issues created by the `/to-issues` skill get tracked and implemented in this repo.
|
||||
Note (2026-07-16): the `/to-issues` skill was renamed to `/to-tickets` in Matt Pocock's v1.1 skill set.
|
||||
|
||||
How issues created by the `/to-tickets` skill get tracked and implemented in this repo.
|
||||
|
||||
## Tracker
|
||||
|
||||
|
|
@ -33,7 +35,7 @@ tea issues <N> --repo jared/cc-os # view one issue's body
|
|||
|
||||
## Implement
|
||||
|
||||
There is **no auto-trigger and no `/grab` command**. Issues from `/to-issues` are written as independently-grabbable tracer-bullet slices. To implement:
|
||||
There is **no auto-trigger and no `/grab` command**. Issues from `/to-tickets` are written as independently-grabbable tracer-bullet slices. To implement:
|
||||
|
||||
1. Pick the next **unblocked** issue (check the "Blocked by" line in the body — slices often form a linear chain).
|
||||
2. Hand it to a coding session: _"implement issue #N from forgejo jared/cc-os"_.
|
||||
|
|
@ -48,4 +50,4 @@ tea issues close <N> --repo jared/cc-os
|
|||
|
||||
## Caveat
|
||||
|
||||
The Matt-Pocock `to-issues` / `triage` skills default to **GitHub** and were never wired to this Forgejo/`tea` backend for cc-os (no `docs/agents/` config, no `.scratch/`). Re-running them assumes GitHub. Running `/setup-matt-pocock-skills` and describing the `tea`/Forgejo workflow would wire them to the right tracker.
|
||||
The Matt-Pocock `to-tickets` (formerly `to-issues`) / `triage` skills default to **GitHub** and were never wired to this Forgejo/`tea` backend for cc-os (no `docs/agents/` config, no `.scratch/`). Re-running them assumes GitHub. Running `/setup-matt-pocock-skills` and describing the `tea`/Forgejo workflow would wire them to the right tracker.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ write it and ensure its labels exist.
|
|||
## One tracker, both jobs
|
||||
|
||||
Per ADR-0042 there is exactly one tracker per project. It holds both task state (labels)
|
||||
and durable specs (issue bodies, `/to-issues` slices, PRDs) — there is no second surface.
|
||||
and durable specs (issue bodies, `/to-tickets` slices, PRDs) — there is no second surface.
|
||||
Valid tracker key formats (exactly one, written to `.cc-os/config`'s `tracker` key):
|
||||
`forgejo:<owner>/<repo>` | `github:<owner>/<repo>` | `repo:<path>`. `planka:<board>` is
|
||||
rejected — `config-write` and the os-status `tracker-configured` check both reject it with
|
||||
|
|
|
|||
|
|
@ -1,127 +1,99 @@
|
|||
# os-sdlc — overview (launching point, v0.1)
|
||||
# os-sdlc — overview & concept map (v0.2)
|
||||
|
||||
Status: scaffold only. No skills/agents/hooks/scripts are implemented yet — this
|
||||
document exists to anchor a follow-up brainstorming session, not to lock a design.
|
||||
_Last updated: 2026-07-16. Status: design mapped, no implementation yet._
|
||||
_This is the single entry point: an AI pointed here loads only the reference/
|
||||
nodes its task needs, following the map below._
|
||||
|
||||
## Why this plugin exists
|
||||
|
||||
Matt Pocock (mattpocock/skills) shipped a v1.1 lifecycle update (2026-07-14) that
|
||||
turned his skill set from a planning tool into a full grill → to-spec → to-tickets →
|
||||
implement → code-review → commit pipeline. Separately, `~/dev/delta-refinery` runs a
|
||||
heavier, DB-backed, multi-level pipeline (System Design → Behavioral Design →
|
||||
Architecture → Slicer → Requirements) with named agent roles per level and a
|
||||
Pre/Post/Handoff pattern for resumable multi-agent work.
|
||||
Blend two proven inputs into one harness-driven SDLC "factory":
|
||||
|
||||
`os-sdlc` is where cc-os adapts the good parts of both — Matt's lightweight linear
|
||||
lifecycle and Delta Refinery's structured multi-level handoff discipline — into the
|
||||
existing os-* family, wired to `os-backlog` (tickets/tracker) and `os-adr` (decision
|
||||
gate), rather than reinventing either. See
|
||||
[docs/adr/0037](../../docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md)
|
||||
for why this is a plugin inside cc-os rather than a separate `cc-sdlc` marketplace.
|
||||
- **Matt Pocock's v1.1 skill lifecycle** (wayfinder/grill → to-spec → to-tickets →
|
||||
implement → code-review → commit) — lightweight, linear, skill-shaped. Notes:
|
||||
SecondBrain vault note `matt-pocock-skills-v1-1-changes.md`.
|
||||
- **DeltaRefinery** (`~/dev/delta-refinery`) — the user's prior multi-level pipeline.
|
||||
Retrospective (2026-07-16): keep its virtues — everything deterministic is
|
||||
mechanical; single-job agents with minimal read/communicate/tool surfaces;
|
||||
hook-run tests (the programmer never runs its own tests). Drop its failure
|
||||
modes — headless-run allotment cost, and per-example TDD granularity (batch to
|
||||
one-ticket grain instead).
|
||||
|
||||
## Scope: not just skills
|
||||
Placement and scope are decided in
|
||||
[docs/adr/0037](../../docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md):
|
||||
a plugin inside cc-os carrying skills + agents + hooks + reference + scripts,
|
||||
composing with `os-backlog` (git issues — Planka retired by ADR-0042), `os-adr`,
|
||||
`os-vault`, and `os-context` rather than reinventing any of them.
|
||||
|
||||
Unlike most current cc-os plugins, `os-sdlc` is expected to carry all of:
|
||||
- **skills/** — the lifecycle verbs (`review` is the first: cherry-picks Matt's
|
||||
standards-conformance + spec-fidelity + Fowler refactor-smell axes into a new
|
||||
`/os-sdlc:review`, coexisting with the existing generic `/code-review`).
|
||||
- **agents/** — named roles for pipeline stages, in the spirit of Delta Refinery's
|
||||
per-level agent rosters, sized down to what a lightweight harness actually needs.
|
||||
- **hooks/** — session/state wiring where a deterministic check beats a skill.
|
||||
- **reference/** — general best-practice material by language/framework/pattern that
|
||||
pipeline stages can pull from (not client- or project-specific — that stays in the
|
||||
vault).
|
||||
- **scripts/** — mechanical CLI tooling supporting the above (candidate for the
|
||||
ADR-0025 lib/+bin/ Ruby structure once real logic exists).
|
||||
## Concept map
|
||||
|
||||
## Working philosophy this plugin should encode
|
||||
Each node is an independent context in `reference/`. Edges are "design here
|
||||
constrains/feeds design there." Decomposing a node into tickets = grill its
|
||||
"Open questions" section, then `to-spec` → `to-tickets` as usual.
|
||||
|
||||
Carried over verbatim from the brainstorming that led here, because it's the design
|
||||
target, not just a preference:
|
||||
```mermaid
|
||||
graph TD
|
||||
ST[spec-and-ticket-layer] --> PS[pipeline-stages]
|
||||
PS --> DG[deterministic-gates]
|
||||
PS --> AD[agent-design-principles]
|
||||
PS --> WP[worktree-parallelism]
|
||||
DG --> PF[plugin-factory]
|
||||
PS --> PO[pipeline-observability]
|
||||
PS -.blocked stage.-> NAT[never-ask-twice]
|
||||
NAT <--> SIL[self-improvement-loops]
|
||||
PO --> SIL
|
||||
SIL --> PF
|
||||
PS -.deferred.-> HZ[horizon]
|
||||
WP -.deferred.-> HZ
|
||||
NAT -.mobbin.-> HZ
|
||||
```
|
||||
|
||||
- **Draft-then-refine over get-it-perfect-up-front.** Autoresearch-style loop: draft
|
||||
an idea, implement a first pass, audit process and outcome, hypothesize an
|
||||
improvement, iterate. Applies to both the artifacts os-sdlc produces (specs,
|
||||
tickets, code) and to os-sdlc's own design.
|
||||
- **Goal is throughput at trust, not just automation.** The target is being able to
|
||||
automate large chunks of the dev process for big upcoming projects — "move at the
|
||||
speed of thought" — which requires the pipeline to be trustworthy enough at each
|
||||
stage that skipping human review of that stage is safe, not just fast.
|
||||
- **Composability with the rest of cc-os is a hard constraint**, not a nice-to-have:
|
||||
os-sdlc must interoperate with `os-backlog` (tickets), `os-adr` (decisions),
|
||||
`os-vault` (cross-project knowledge) — ADR-023's "os-* plugins cooperate" bet
|
||||
applies here directly.
|
||||
## Index
|
||||
|
||||
## Known inputs for the follow-up brainstorming session
|
||||
| Node | Status | One-liner |
|
||||
|---|---|---|
|
||||
| [spec-and-ticket-layer](reference/spec-and-ticket-layer.md) | settled direction | Git issues (Forgejo/GitHub per tracker key) are the durable spec layer; Pocock verbs map onto it |
|
||||
| [pipeline-stages](reference/pipeline-stages.md) | direction | The v1 tracer bullet: `/implement` → test-writer → red-assert → programmer → green-assert → reviewer → human merge |
|
||||
| [deterministic-gates](reference/deterministic-gates.md) | settled | Hooks, not agents, run tests/lint; red/green asserted mechanically; green command pluggable per project |
|
||||
| [agent-design-principles](reference/agent-design-principles.md) | settled | Single job, minimal tool allowlist (programmer: no Bash), settled facts in via prompt, minimum out via return format |
|
||||
| [worktree-parallelism](reference/worktree-parallelism.md) | direction | Worktree-per-spec, sequential tickets within a spec, parallel across specs, human merge gate |
|
||||
| [pipeline-observability](reference/pipeline-observability.md) | direction | What a run writes down (exhaust), where it lives, predefined lifespans (os-doc-hygiene); copy-tag-audit pattern feeds the loops |
|
||||
| [never-ask-twice](reference/never-ask-twice.md) | direction | The agency mechanism: two-tier lookup → mint-time scope classification → audit promotion; decision-category autonomy labels |
|
||||
| [self-improvement-loops](reference/self-improvement-loops.md) | direction | Session audits, ADR audits, eval harnesses, skill-lint — each catches a different drift |
|
||||
| [plugin-factory](reference/plugin-factory.md) | direction | Same factory builds plugins from a PRD; the eval harness is the green command |
|
||||
| [horizon](reference/horizon.md) | horizon | Wake-on-trigger, Herdr controller, router agent, Mobbin — preserved intent, explicitly out of v1 |
|
||||
|
||||
- Matt Pocock v1.1 lifecycle notes: `docs/matt-pocock-skills-v1.1-notes.md`.
|
||||
- Delta Refinery structure (facts gathered this session, not yet written up as a
|
||||
standalone doc): 5-level `PipelineRunner`/`PipelineOrchestrator`, per-level agent
|
||||
rosters under `.claude/agents/{prd,functional_spec,technical_spec,requirements}/`,
|
||||
intra-level in-memory `Handoff` + inter-level DB-persisted `Artifact#structured_content`
|
||||
for resumability, two composition roots (`HeadwatersComposition` full pipeline vs.
|
||||
`ProductionComposition` requirement-level-only).
|
||||
- Existing cc-os pieces this must integrate with: `os-backlog` (capture/list/route),
|
||||
`os-adr` (find/create/init/migrate), `os-vault` (query/write/onboard-project).
|
||||
- Open question carried into the brainstorm: how much of Delta Refinery's
|
||||
resumable-handoff machinery is worth adopting now vs. deferred until a concrete
|
||||
multi-session pipeline actually needs it (avoid building it ahead of a real need).
|
||||
## Working philosophy (design target, not preference)
|
||||
|
||||
## ADW taxonomy input (2026-07-14 session)
|
||||
- **Draft-then-refine over get-it-perfect-up-front** — applies to the factory's
|
||||
artifacts and to the factory itself.
|
||||
- **Throughput at trust, not just automation** — a stage is done when skipping
|
||||
human review of it is *safe*; trust is earned in units and made durable
|
||||
(see never-ask-twice).
|
||||
- **Three actors** (vault note `agentic-sdlc-ai-developer-workflow-taxonomy.md`):
|
||||
every stage first asks whether it needs **code** (deterministic, free),
|
||||
**engineer** (fixed start/end gates), or **agent** (judgment) — never default
|
||||
to agent.
|
||||
- **Composability with os-* siblings is a hard constraint** (ADR-023).
|
||||
|
||||
Cross-project methodology reference, not repo-specific: see the vault note
|
||||
`agentic-sdlc-ai-developer-workflow-taxonomy.md` (SecondBrain) — a taxonomy of AI Developer
|
||||
Workflow (ADW) structures from IndyDevDan's "Forget Loop Engineering" video (mermaid diagrams
|
||||
included, with `[dan]`/`[jrs]` provenance tags separating his claims from cc-os-specific
|
||||
extrapolation). Read it before designing os-sdlc's pipeline shape; the plan below is the
|
||||
repo-specific slice of that broader taxonomy.
|
||||
## Build sequencing
|
||||
|
||||
Three actors of value creation apply directly to os-sdlc's component design: **code**
|
||||
(deterministic, free, most reliable — lint/format/test/CI/ticket-state transitions),
|
||||
**engineer** (the two fixed constraints: prompting/planning at the start, reviewing at the
|
||||
end), **agent** (judgment work: planning, building, scouting). Every os-sdlc pipeline stage
|
||||
should be built by first asking which of the three actors it actually needs — don't default
|
||||
to "agent" for something code or a human gate should own.
|
||||
v1 = the tracer bullet in [pipeline-stages](reference/pipeline-stages.md),
|
||||
triggered manually, walked by hand once before wiring into skills/hooks/agents.
|
||||
Everything in [horizon](reference/horizon.md) stays unbuilt until the interactive
|
||||
factory is trusted. Open items live per-node in each doc's "Open questions" —
|
||||
this file carries none.
|
||||
|
||||
## First-iteration build plan: a single tracer-bullet ADW
|
||||
**Grill queue** (decided 2026-07-16): the critical path is
|
||||
[spec-and-ticket-layer](reference/spec-and-ticket-layer.md) →
|
||||
[pipeline-stages](reference/pipeline-stages.md) — grill in that order first.
|
||||
Then [never-ask-twice](reference/never-ask-twice.md) +
|
||||
[self-improvement-loops](reference/self-improvement-loops.md) (can run in
|
||||
parallel with pipeline build; NAT's formalization ADR is independent), then
|
||||
[horizon](reference/horizon.md). The remaining nodes' open questions are
|
||||
implementation-time calls, not grill material.
|
||||
|
||||
Per the vault note's escalation ladder, and per standing tracer-bullet convention, the first
|
||||
build target is the smallest complete loop, not the software factory. Scope:
|
||||
## Sources
|
||||
|
||||
**One worktree, one pipeline**: `ticket intake → build agent → lint/format/test (hooks) →
|
||||
engineer review → ship`. Sandboxes, N-way worktree fan-out, the hotfix ADW, and the software
|
||||
factory router are explicitly deferred — documented in the vault note, not built here.
|
||||
|
||||
Step by step:
|
||||
|
||||
1. **Ticket intake** (code, not agent). Reuse `os-backlog` as the trigger: a card moving to
|
||||
`Doing` (or a linked Forgejo issue via `/to-tickets`) is the pipeline's entry point. No new
|
||||
ticketing system — os-sdlc consumes os-backlog's state, per ADR-0037's composability
|
||||
constraint.
|
||||
2. **Build agent** (agent, minimal tools). New `os-sdlc` agent definition: system prompt scoped
|
||||
to "write/modify code to satisfy the spec," tool grants limited to `Read`/`Write`(/`Edit`) —
|
||||
no `Bash`. It cannot run tests or linting itself; it only ever sees pass/fail feedback handed
|
||||
back to it.
|
||||
3. **Lint/format/test gate** (code, via hooks — delta-refinery-style Pre/Post/Handoff, not a
|
||||
skill-embedded step). A `PostToolUse`-style hook (or a small script the pipeline invokes
|
||||
between agent turns) runs the project's lint/format/test commands after each build-agent
|
||||
turn. On failure, the failing output is fed back into the *same* build-agent session as the
|
||||
next turn's context (per Dan's separation-of-concerns principle). On pass, advance.
|
||||
4. **Engineer review** (human gate). Standard PR/diff review — no change from how review works
|
||||
today; the pipeline's job is to get a clean, tested diff in front of the engineer, not to
|
||||
replace this gate.
|
||||
5. **Ship** (code). Merge + whatever this repo's existing deploy path is — os-sdlc does not
|
||||
own deploy; it hands off a mergeable, reviewed change.
|
||||
|
||||
Each step above should be walked by hand first (per Dan's second tip) before being wired into
|
||||
skills/hooks/agents — run the lint/test loop manually against a real small change, confirm the
|
||||
feedback-loop shape works, *then* automate it.
|
||||
|
||||
## Not decided yet (do not assume in implementation)
|
||||
|
||||
- Which of Matt's skills get adopted as-is vs. adapted vs. skipped, beyond `review`.
|
||||
- Whether `implement` is adopted as a thin router as-is, or redesigned as a
|
||||
Delta-Refinery-style level with named sub-roles.
|
||||
- Whether `wayfinder` (multi-issue planning for big-plan decomposition) subsumes or
|
||||
sits alongside a Delta-Refinery-style level structure.
|
||||
- Any hook or agent definitions — none exist yet.
|
||||
- Vault: `matt-pocock-skills-v1-1-changes.md`, `agentic-sdlc-ai-developer-workflow-taxonomy.md`
|
||||
- Repo: ADR-0037 (placement), ADR-0042 (git-issues-only backlog), `~/dev/delta-refinery`
|
||||
- Tracked follow-ups: cc-os Forgejo issues #71 (audit criteria), #72 (skill-lint), #73 (worktree tracker resolution)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,52 @@
|
|||
# agent design principles
|
||||
|
||||
_Status: settled — as of 2026-07-16_
|
||||
_Connects to: [pipeline-stages](pipeline-stages.md), [deterministic-gates](deterministic-gates.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
Fixes the shape every os-sdlc agent definition must follow: one job, minimal reads, minimal
|
||||
tools, minimal returns. Load this before writing or reviewing any `agents/*.md` definition in
|
||||
this plugin.
|
||||
|
||||
## Design
|
||||
|
||||
- **One clearly-defined job per agent.** It reads only what it needs for that job; it returns
|
||||
the minimum under an explicit return format, so the next stage's context stays clean rather
|
||||
than accumulating everything every prior stage touched.
|
||||
- **Minimal tool allowlists via `tools:` frontmatter** in `agents/*.md`. The
|
||||
programmer/build agent gets `Read`/`Write`/`Edit` only — no `Bash`. This is a deliberate
|
||||
`[jrs]` decision in the vault taxonomy note, stronger than IndyDevDan's "separate
|
||||
invocation" stance: rather than merely running build and test in separate agent
|
||||
invocations, the build agent is architecturally incapable of running tests or shells at
|
||||
all. No `WebFetch`/MCP/other-plugin tools unless the specific job needs them. Effect
|
||||
observed in DeltaRefinery: agents scoped this tightly were more focused, cheaper per
|
||||
invocation, and faster — the constraint is a feature, not friction.
|
||||
- **Settled facts travel in via the spawn prompt** — an agent never "re-reads what the
|
||||
orchestrator already read." The orchestrating stage resolves context once and hands the
|
||||
agent exactly what it needs in the prompt itself.
|
||||
- **Inter-stage state travels via small on-disk handoff artifacts** — a file-based analog of
|
||||
DeltaRefinery's in-memory `Handoff` (intra-level) and DB-persisted `Artifact` (inter-level).
|
||||
os-sdlc keeps this lightweight (files, not a database) because v1 is a single-session
|
||||
tracer-bullet pipeline, not DeltaRefinery's multi-session resumable system.
|
||||
- **Model tiering:** mechanical work → haiku; judgment work → sonnet; hard reasoning → opus.
|
||||
Applied per-agent-definition, not per-pipeline — a test-writer doing mechanical
|
||||
transcription of ticket acceptance criteria into test stubs is a different tier than a
|
||||
reviewer judging spec alignment.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Concrete handoff artifact file format (plain markdown, JSON, frontmatter'd markdown) —
|
||||
not yet chosen.
|
||||
- Whether DeltaRefinery-style persisted resumability is needed before multi-session
|
||||
pipelines actually exist. Per the standing "don't build ahead of need" convention (see
|
||||
[pipeline-stages](pipeline-stages.md)'s tracer-bullet framing), this stays undecided until a
|
||||
real multi-session use case shows up.
|
||||
|
||||
## Sources
|
||||
|
||||
- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md` (`[jrs]` tool-allowlist
|
||||
stance vs. `[dan]` separate-invocation stance)
|
||||
- `~/dev/delta-refinery` (Handoff/Artifact pattern this generalizes from)
|
||||
- `plugins/os-sdlc/OVERVIEW.md`
|
||||
- 2026-07-16 design session (this doc's origin)
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
# deterministic gates
|
||||
|
||||
_Status: settled — as of 2026-07-16_
|
||||
_Connects to: [pipeline-stages](pipeline-stages.md), [agent-design-principles](agent-design-principles.md), [plugin-factory](plugin-factory.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
States the core rule that keeps os-sdlc's trust model cheap: agents never self-certify their
|
||||
own work, hooks do. Load this when designing any pipeline stage that checks correctness, or
|
||||
when wiring hook events for os-sdlc.
|
||||
|
||||
## Design
|
||||
|
||||
- **Core rule: agents never run tests/lint/format.** Hooks do — either Stop/SubagentStop
|
||||
hooks, or a between-turn pipeline script. This is the mechanism, not just a preference: it
|
||||
is what makes "red→green" something the pipeline *proves* rather than something an agent
|
||||
*claims*, at zero additional LLM cost.
|
||||
- On failure, the failing output is injected into the same agent's next turn as context — not
|
||||
routed to a different agent, so the agent that wrote the code gets the direct feedback loop.
|
||||
A max-iteration counter escalates to the human after N failed attempts, rather than looping
|
||||
indefinitely.
|
||||
- **Red-assert and green-assert gates** (defined in
|
||||
[pipeline-stages](pipeline-stages.md)) are the two concrete applications of this rule in the
|
||||
v1 pipeline: red-assert proves the tests actually exercise unbuilt behavior, green-assert
|
||||
proves the implementation actually satisfies them.
|
||||
- **Pluggable green command.** A per-project config value — proposed home: next to the
|
||||
tracker key in `.cc-os/config` — names the command that proves work green: `rake test` +
|
||||
rubocop for a Rails app, the eval harness for a cc-os plugin itself. This one indirection is
|
||||
what lets the same factory drive arbitrarily different project types without os-sdlc knowing
|
||||
anything about their toolchains.
|
||||
- **Three-actors framing** (from the SecondBrain vault note
|
||||
`agentic-sdlc-ai-developer-workflow-taxonomy.md`, IndyDevDan): **code** (deterministic,
|
||||
free, most reliable), **engineer** (fixed start/end points — prompting and reviewing),
|
||||
**agent** (judgment, most expensive and most variable). Every stage in os-sdlc is designed
|
||||
by first asking which actor it actually needs — the default is never "agent."
|
||||
Test-execution and lint/format are unambiguously **code**-actor work; routing them through
|
||||
an agent would be strictly worse on cost, reliability, and speed.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Exact hook events to use (Stop/SubagentStop) vs. a pipeline-invoked script called between
|
||||
agent turns — a runtime/implementation choice, not yet made.
|
||||
- Where the max-iteration count lives (hook config, `.cc-os/config`, or hardcoded per stage)
|
||||
and what the escalation-to-human path looks like concretely.
|
||||
|
||||
## Sources
|
||||
|
||||
- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md` (three-actors framing,
|
||||
IndyDevDan)
|
||||
- `~/dev/delta-refinery` (Pre/Post/Handoff pattern this generalizes from)
|
||||
- `plugins/os-sdlc/OVERVIEW.md`
|
||||
- ADR-0037, ADR-0042
|
||||
- 2026-07-16 design session (this doc's origin)
|
||||
|
|
@ -0,0 +1,65 @@
|
|||
# horizon
|
||||
|
||||
_Status: horizon — explicitly not being built yet; this doc exists to keep these OUT of v1 scope while preserving the design intent — as of 2026-07-16_
|
||||
_Connects to: [pipeline-stages](pipeline-stages.md), [worktree-parallelism](worktree-parallelism.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
Parks the ideas that shaped the 2026-07-16 design session but are deliberately excluded
|
||||
from v1, so they don't get silently reintroduced as scope creep and don't get lost either.
|
||||
Load this when scoping any future os-sdlc milestone, or when a v1 stage's design seems to be
|
||||
straining toward one of these — that strain is expected; the boundary is intentional.
|
||||
|
||||
## Design
|
||||
|
||||
- **Wake-on-trigger.** An issue state change (e.g. label added, ticket moved to "ready")
|
||||
wakes the pipeline instead of a human running `/implement` manually. v1 is deliberately
|
||||
manual — the factory is developed and iterated within interactive sessions until it's
|
||||
trusted to run autonomously. Autonomy is earned the same way [never-ask-twice](never-ask-twice.md)
|
||||
describes for individual decisions, applied here to the pipeline's own trigger.
|
||||
- **Herdr integration** (https://herdr.dev/docs/, socket API at
|
||||
https://herdr.dev/docs/socket-api/). A small deterministic controller — no LLM — opens
|
||||
panes, starts interactive Claude Code sessions, sends stage prompts (send_keys-style),
|
||||
detects completion, reads the result, and triggers the next stage. Rationale: Anthropic
|
||||
now charges extra time allotment for headless runs, so driving automated coding through
|
||||
headless mode would eat into the allotment the Max plan's coding was bought for; Herdr-driven
|
||||
*interactive* sessions bill as normal usage instead, preserving that allotment for other
|
||||
purposes (e.g. a future Hermes integration). **Load-bearing unknown to spike before leaning
|
||||
on this at all: does the Herdr socket API give reliable "agent finished" detection, or only
|
||||
heuristic pane-scraping?** If it's only heuristic scraping, completion-detection false
|
||||
positives/negatives could silently corrupt pipeline stage transitions — this needs to be
|
||||
proven, not assumed, before Herdr becomes load-bearing infrastructure.
|
||||
- **Router agent** dispatching tickets to specialized pipelines (chore/bug/feature/hotfix,
|
||||
each with a different stage shape). Deferred until v1's single pipeline shape is proven
|
||||
insufficient — matches the ladder described in the SecondBrain vault taxonomy note; adding
|
||||
a router before it's needed would be exactly the premature-granularity mistake
|
||||
[pipeline-stages](pipeline-stages.md) already rejected once (the seam-creator/implementor
|
||||
split).
|
||||
- **Mobbin UX decision-tree seeding.** See [never-ask-twice](never-ask-twice.md) — a
|
||||
pre-seeded convention library (mobbin.com) for the UI-flow decision category, letting
|
||||
front-end decisions start at `semi` autonomy instead of `hitl`. Horizon because it depends
|
||||
on the category-autonomy mechanism existing and being trusted first.
|
||||
- **End-state vision** (verbatim intent from the user, 2026-07-16): plan alongside the AI in
|
||||
one window; when ready, work is delegated, automatically prioritized, decomposed, and
|
||||
worked until complete or blocked; blockages are resolved immediately AND minted into
|
||||
ADRs/best practices/conventions so that next time the AI confidently picks the obvious path
|
||||
or presents a narrowed choice; the factory self-improves over time and agents take agency
|
||||
as confidence in their decisions is earned.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Whether wake-on-trigger and Herdr integration are actually separable milestones (wake-on-trigger
|
||||
could plausibly ship without Herdr, using headless mode at the accepted allotment cost) or
|
||||
whether they're coupled in practice.
|
||||
- What "trusted to run autonomously" concretely means as an exit criterion for v1 — likely an
|
||||
ask-rate threshold fed by [never-ask-twice](never-ask-twice.md)'s audits, but not yet defined.
|
||||
- Whether the router-agent ladder rungs (chore/bug/feature/hotfix) match the vault taxonomy
|
||||
note's categories exactly or need adjustment once real ticket volume exists.
|
||||
|
||||
## Sources
|
||||
|
||||
- Herdr docs: https://herdr.dev/docs/, https://herdr.dev/docs/socket-api/
|
||||
- SecondBrain vault: taxonomy/ladder note (chore/bug/feature/hotfix router categories)
|
||||
- mobbin.com (design-pattern library)
|
||||
- ADR-0037
|
||||
- 2026-07-16 design session (this doc's origin, including verbatim end-state vision)
|
||||
|
|
@ -0,0 +1,76 @@
|
|||
# never ask twice
|
||||
|
||||
_Status: direction — as of 2026-07-16_
|
||||
_Connects to: [self-improvement-loops](self-improvement-loops.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [horizon](horizon.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
The agency mechanism, and the most important node in this reference set. States the
|
||||
operating principle that lets the factory earn autonomy over time instead of asking the
|
||||
human the same question on every run. Load this before designing any blocked-stage
|
||||
behavior, any human-input point in the pipeline, or ADR-0037's follow-on formalization ADR.
|
||||
|
||||
## Design
|
||||
|
||||
- **Operating principle: the factory never asks the human the same question twice.** Trust
|
||||
is earned in units, and every unit is made durable and reusable. Goal state: the human is
|
||||
only presented options when the factory genuinely needs direction — not because a decision
|
||||
that was already made once was forgotten.
|
||||
- No new storage system and no literal decision-tree engine. The "tree" is the existing ADR
|
||||
corpus plus vault conventions; os-sdlc adds only wiring on top of os-adr and os-vault.
|
||||
Three thin pieces:
|
||||
1. **Two-tier lookup at block time.** Before any question reaches the human, the blocked
|
||||
stage runs a mandatory, mechanical chain: `/os-adr:find` over the repo's ADRs first,
|
||||
then `/os-vault:query` over `domain/`/`tool/`/`convention/` facets. Only a genuine miss
|
||||
on both tiers produces a human-facing question.
|
||||
2. **Scope classification at mint time.** When the human unblocks a stage by answering,
|
||||
the factory asks one follow-up: "does this generalize beyond this repo?" No → record a
|
||||
repo-local ADR only. Yes → a vault convention note becomes the source of truth, and the
|
||||
repo ADR records the local adoption with a link back to it. The ask is not complete
|
||||
until the record exists — an answered-but-unrecorded question is the failure mode this
|
||||
whole mechanism exists to prevent.
|
||||
3. **Promotion by audit, not memory.** A decision minted local that later blocks a second
|
||||
project is a recurrence — visible across blocked-stage logs, not tracked live. A
|
||||
periodic audit (see [self-improvement-loops](self-improvement-loops.md)) sees the
|
||||
recurrence and promotes the answer to a vault convention.
|
||||
- **Decision-category autonomy labels**, generalized from individual tickets to decision
|
||||
*categories* (e.g. dependency choice, schema-migration approach, UI flow pattern):
|
||||
- `afk-ready` + a covering record → proceed and cite the record.
|
||||
- `semi` → proceed, but flag the decision in the stage report for human review.
|
||||
- `hitl`, or no coverage at all → stop and ask.
|
||||
Promotion and demotion of categories happens only in periodic audits, never mid-run.
|
||||
- **Cross-project answer, worked example:** a decision minted while building rails app A
|
||||
should be available when building rails app B. Repo ADRs are deliberately project-local
|
||||
(they record local adoption, not universal truth); the vault is the cross-project layer.
|
||||
os-sdlc doesn't change this split — it adds the lookup chain, the mint ritual, and the
|
||||
audit-driven promotion path on top of it.
|
||||
- **Honest limit:** this mechanism guarantees the *plumbing* — a decision recorded once is
|
||||
findable everywhere it applies — not the *judgment* that the agent applies the right
|
||||
convention in an ambiguous case. Judgment quality is proven only by accumulated audits.
|
||||
Expect the ask-rate to fall as categories graduate from `hitl`/`semi` to `afk-ready`; a
|
||||
category that graduates too early gets demoted, with the ADR trail showing exactly which
|
||||
decision went wrong and why.
|
||||
- **Mobbin** (mobbin.com, a design-pattern reference library) as a future pre-seeded
|
||||
convention library for the UI-flow decision category — would let front-end decisions start
|
||||
at `semi` instead of `hitl` from day one. This is horizon-scoped (see
|
||||
[horizon](horizon.md)) but validates that the category-autonomy frame generalizes to
|
||||
externally-sourced conventions, not just self-mined ones.
|
||||
- This mechanism spans os-sdlc, os-adr, and os-vault jointly and gets its own ADR when
|
||||
formalized — it is not owned by any single plugin.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Block-report format: what a blocked stage writes when it stops to ask (must carry enough
|
||||
context for the two-tier lookup to be re-run later without re-asking).
|
||||
- Where decision-category labels live (ADR frontmatter? a small config file? vault note
|
||||
frontmatter?) and who assigns the initial label for a brand-new category.
|
||||
- Audit cadence for promotion/demotion (tied to [self-improvement-loops](self-improvement-loops.md)'s
|
||||
ADR-audit loop, but not yet fixed).
|
||||
|
||||
## Sources
|
||||
|
||||
- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
|
||||
- os-adr `find`/`create` skills; os-vault `query`/`write` skills
|
||||
- SecondBrain vault: taxonomy/ladder note (referenced by [horizon](horizon.md))
|
||||
- mobbin.com (design-pattern library, horizon reference)
|
||||
- 2026-07-16 design session (this doc's origin)
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
# pipeline observability
|
||||
|
||||
_Status: direction — as of 2026-07-16_
|
||||
_Connects to: [pipeline-stages](pipeline-stages.md), [self-improvement-loops](self-improvement-loops.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines what a pipeline run writes down — its exhaust — where it goes, and how long it
|
||||
lives. The self-improvement loops and the never-ask-twice promotion mechanism are only as
|
||||
good as this exhaust; it was implicit in the original design and is made explicit here.
|
||||
Load this before designing any run report, audit input, or blocked-stage log.
|
||||
|
||||
## Design
|
||||
|
||||
- **Every run emits exhaust**: stages executed, actor per stage, gate outcomes (red/green,
|
||||
iterations consumed), blocked-stage reports (the questions the pipeline could not
|
||||
auto-resolve — [never-ask-twice](never-ask-twice.md)'s raw input), and a human-facing
|
||||
summary. This is the feed the loops in
|
||||
[self-improvement-loops](self-improvement-loops.md) consume.
|
||||
- **Every exhaust artifact has a predefined lifespan** (composes with os-doc-hygiene):
|
||||
run-scoped scratch dies with the worktree; run reports persist on the ticket; anything
|
||||
durable gets *promoted* to its proper home (ADR, vault note, issue comment) rather than
|
||||
accumulating as clutter. No unbounded log directories.
|
||||
- **Copy → tag → audit pattern** (deterministic where possible, per the three-actor test):
|
||||
the write side is a hook (code actor), the review side is the periodic audit (agent
|
||||
actor). Reference case — ADRs: the ADR-writing skill becomes a named agent whose hook
|
||||
copies every new ADR into the vault at write time; the ADR audit then reads only *virgin*
|
||||
(untagged) vault copies, keeps the durable ones, revises for clarity where needed, and
|
||||
tags them audited — the next round checks only new virgin ADRs. The same pattern
|
||||
generalizes to other streams (blocked-stage reports, run reports): mechanical capture at
|
||||
write time, audit consumes the untagged backlog, tagging marks progress.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Run-report format and home: an issue comment on the ticket (durable, in-tracker, visible
|
||||
at merge review) vs. a file artifact — leaning issue comment.
|
||||
- Lifespan policy per artifact class (scratch / run report / blocked-stage report) and how
|
||||
os-doc-hygiene enforces it.
|
||||
- Which exhaust stream gets the copy-tag-audit hook first (ADRs are the obvious pilot).
|
||||
|
||||
## Sources
|
||||
|
||||
- 2026-07-16 design session — user-identified gap ("I assumed this mechanism was baked into
|
||||
the concept") + the ADR copy-tag-audit proposal
|
||||
- os-doc-hygiene plugin (lifespan enforcement)
|
||||
- ADR-0037
|
||||
|
|
@ -0,0 +1,81 @@
|
|||
# pipeline stages
|
||||
|
||||
_Status: direction — as of 2026-07-16_
|
||||
_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [pipeline-observability](pipeline-observability.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines the v1 tracer-bullet pipeline shape for `/implement <ticket>`: the ordered stages,
|
||||
which actor (code/engineer/agent) owns each, and the two decisions that keep the pipeline at
|
||||
one-agent-one-job grain. Load this before designing any pipeline stage, skill, or agent
|
||||
definition for os-sdlc.
|
||||
|
||||
## Design
|
||||
|
||||
Manually triggered by `/implement <ticket>`. Stages, in order:
|
||||
|
||||
1. **Ticket intake** (code) — reads the issue via the `os-backlog` tracker key
|
||||
(`.cc-os/config`); no new ticketing system, per ADR-0037's composability constraint.
|
||||
2. **Test-writer agent** — writes failing tests from the ticket, nothing else.
|
||||
3. **Red-assert gate** (deterministic hook) — runs the suite; it MUST fail. A pass here means
|
||||
vacuous tests or the feature already exists — either way the pipeline halts rather than
|
||||
proceeding on a false signal.
|
||||
4. **Programmer agent** — makes the tests pass. One agent, not a seam-creator/implementor
|
||||
split.
|
||||
5. **Green-assert gate** (deterministic hook) — suite + lint must pass. Failures are
|
||||
auto-fed back into the same programmer's next turn; a max-iterations cap escalates to the
|
||||
human rather than looping forever.
|
||||
6. **Reviewer agent** — a *named agent* (not a skill), so its tool surface is minimal and
|
||||
its context never leaks into the orchestrator's (see
|
||||
[agent-design-principles](agent-design-principles.md)). It reads only a hook-assembled
|
||||
context packet — test status from the green-assert gate (passing, unless max-iterations
|
||||
escalated), a mechanically generated diff, and the spec/ticket — gathered into one
|
||||
document by a code-actor hook before the agent is invoked; the reviewer runs nothing
|
||||
itself. Two ordered checks: first tests align with the spec/ticket, then code aligns
|
||||
with both tests and spec. Order matters — misaligned tests invalidate a "code passes
|
||||
tests" result. ADR-0037's `/os-sdlc:review` (standards-conformance + spec-fidelity +
|
||||
Fowler refactor smells) is satisfied by this same agent; if standalone review of an
|
||||
arbitrary diff is wanted outside a pipeline run, a thin skill wrapper dispatches the
|
||||
agent with a hand-assembled packet — one reviewer, two entry points.
|
||||
7. **Cleanup & report** (agent/code mix) — trims scratch artifacts, produces a summary for the
|
||||
human. What gets written, where, and for how long is defined in
|
||||
[pipeline-observability](pipeline-observability.md).
|
||||
8. **Human merge gate** — v1 has no automated merge; see
|
||||
[worktree-parallelism](worktree-parallelism.md).
|
||||
|
||||
Two decisions fix the grain of this pipeline:
|
||||
|
||||
- **One programmer agent, not seam-creator/implementor.** The seam is not a judgment
|
||||
boundary — splitting it adds a handoff and context loss for no trust gain. This is exactly
|
||||
the over-granularity DeltaRefinery suffered from. Revisit only if audits show programmers
|
||||
entangling design decisions to cheat tests (i.e., gaming the green-assert gate instead of
|
||||
solving the ticket).
|
||||
- **Refactor is not a standing stage.** The reviewer's critique triggers a correction loop —
|
||||
re-invoking the programmer with findings — using the same feedback mechanism as a failing
|
||||
gate, rather than a dedicated pipeline stage.
|
||||
|
||||
Grain: one ticket, one vertical slice. TDD is internal to the stage (test-writer then
|
||||
programmer within one ticket's run), never orchestrated per-example from outside — that
|
||||
per-example granularity was a DeltaRefinery downside being deliberately dropped.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Skill/agent naming for each stage (test-writer, programmer, reviewer) — must follow the
|
||||
cc-os naming convention before anything ships.
|
||||
- Whether a cheap tests-vs-spec review should run *before* the programmer stage in later
|
||||
versions, to catch misaligned tests before paying for implementation.
|
||||
- Shape settled 2026-07-16: `/implement` (or our custom successor) is a *skill acting as
|
||||
orchestrator* — slash commands are the user-invocable layer, agents aren't. The skill
|
||||
triggers the agent pipeline, watches over it, adjusts to surprises, and keeps the user
|
||||
in the loop on progress/results. Remaining question: how much of Pocock's `implement`
|
||||
wording survives vs. a from-scratch orchestrator prompt.
|
||||
|
||||
## Sources
|
||||
|
||||
- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
|
||||
- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
|
||||
- `plugins/os-sdlc/OVERVIEW.md`
|
||||
- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md`,
|
||||
`matt-pocock-skills-v1-1-changes.md`
|
||||
- `~/dev/delta-refinery` (prior art, principles kept/dropped as noted above)
|
||||
- 2026-07-16 design session (this doc's origin)
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
# plugin factory
|
||||
|
||||
_Status: direction — as of 2026-07-16_
|
||||
_Connects to: [deterministic-gates](deterministic-gates.md), [self-improvement-loops](self-improvement-loops.md), [pipeline-stages](pipeline-stages.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
States that os-sdlc is the same factory cc-os uses to build its own `os-*` plugins, not a
|
||||
separate meta-tool — and how that reflexive use case is possible without a second pipeline.
|
||||
Load this before scaffolding a new `os-*` plugin, or before designing anything that looks
|
||||
like a "plugin builder" separate from the ticket pipeline in
|
||||
[pipeline-stages](pipeline-stages.md).
|
||||
|
||||
## Design
|
||||
|
||||
- **The same factory builds cc-os plugins from a PRD.** This works because the green command
|
||||
is pluggable per project (see [deterministic-gates](deterministic-gates.md)): for a normal
|
||||
application repo it's `rake test` + lint; for an AiDD-type project (a cc-os plugin) **the
|
||||
eval harness IS the test suite**. TDD becomes eval-driven development — write the eval,
|
||||
watch it fail for the right reason, build the skill until it passes — with no separate
|
||||
pipeline, no special-cased plugin-building mode. The pipeline stages in
|
||||
[pipeline-stages](pipeline-stages.md) run unchanged; only the green-command config value
|
||||
differs.
|
||||
- **Plugins self-evolve after they ship.** Once a plugin exists, its own operation becomes
|
||||
input back into the same factory: audits of sessions it participated in (loop a),
|
||||
ADR-corpus audits touching its decisions (loop b), its own eval-harness regressions (loop
|
||||
c), and direct user feedback all generate improvement tickets. Those tickets re-enter
|
||||
factory intake exactly like any other ticket — a plugin is never "done," it's a standing
|
||||
client of its own factory. See [self-improvement-loops](self-improvement-loops.md) for the
|
||||
four loops that produce this feedback.
|
||||
- This closes the loop cc-os has been running informally (build a plugin, notice drift in
|
||||
use, fix it in a follow-up session) into something the factory itself can drive
|
||||
end-to-end: PRD → spec → tickets → implement → ship → audit → new tickets.
|
||||
|
||||
## Open questions
|
||||
|
||||
- PRD template for plugins specifically — likely narrower than a general product PRD (needs
|
||||
to name: the eval harness location, the green command, which existing `os-*` plugins it
|
||||
composes with per ADR-0037's composability constraint).
|
||||
- Eval-first scaffolding: the red-assert analog for eval-driven development — does
|
||||
`to-tickets`/`/implement` need a variant stage that writes the eval scenario before the
|
||||
skill exists, mirroring the test-writer stage in [pipeline-stages](pipeline-stages.md)?
|
||||
- How improvement tickets are auto-generated from audit findings — format, who/what creates
|
||||
the issue (a code-actor script parsing an audit report, or an agent stage), and how
|
||||
duplicate/overlapping findings across the four loops get deduplicated before hitting the
|
||||
tracker.
|
||||
|
||||
## Sources
|
||||
|
||||
- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
|
||||
- `plugins/os-sdlc/OVERVIEW.md`
|
||||
- `plugins/os-vault/eval/`, `plugins/os-adr/eval/`, `plugins/os-context/eval/`
|
||||
- 2026-07-16 design session (this doc's origin)
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
# self improvement loops
|
||||
|
||||
_Status: direction — as of 2026-07-16_
|
||||
_Connects to: [never-ask-twice](never-ask-twice.md), [plugin-factory](plugin-factory.md), [pipeline-observability](pipeline-observability.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
Names the four periodic audit loops that keep the factory (and the plugins it builds)
|
||||
honest over time, and which of them already exist vs. are new. Load this before designing
|
||||
any audit skill, before scoping ADR-audit work, or before wiring an improvement-ticket
|
||||
generator into the factory.
|
||||
|
||||
## Design
|
||||
|
||||
Four loops, each catching a different kind of drift. None of them fire mid-run — all are
|
||||
periodic, out-of-band audits, deliberately kept separate from the pipeline itself so an
|
||||
audit's own cost/latency never blocks a ticket.
|
||||
|
||||
- **a. Session audits** (exists) — os-context's biweekly IRL audit. Catches behavior drift
|
||||
in how sessions actually run. Needs rework per cc-os Forgejo issue #71: current criteria
|
||||
don't catch expensive-model overuse where delegation or determinism would cut cost with no
|
||||
quality drop — a gap directly relevant to os-sdlc's actor-choice discipline (see
|
||||
[deterministic-gates](deterministic-gates.md)'s code/engineer/agent framing).
|
||||
- **b. ADR audits** (new, proposed 2026-07-16) — catches corpus drift, the counterpart to
|
||||
session audits but aimed at the decision record itself rather than session transcripts.
|
||||
Periodically audits the ADR corpus for: stale decisions, missed promotions to the vault
|
||||
(a local ADR that should have graduated per
|
||||
[never-ask-twice](never-ask-twice.md)'s promotion-by-audit step but didn't), and
|
||||
scope-classification judgment calls that slipped through at mint time. A wrong mint-time
|
||||
call is treated as a delay, not a loss — anything missed gets caught in the next ADR
|
||||
audit, so the loop is self-correcting rather than requiring the mint-time call to be
|
||||
perfect. Proposed mechanics (2026-07-16, user): the copy-tag-audit pattern from
|
||||
[pipeline-observability](pipeline-observability.md) — a hook copies every new ADR into
|
||||
the vault at write time; the audit reads only *virgin* (untagged) copies, keeps the
|
||||
durable ones, revises for clarity, tags them audited; the next round checks only new
|
||||
virgin ADRs. This makes the capture side deterministic and the audit's workload bounded.
|
||||
- **c. Eval harnesses** (exists — autoresearch pattern, already running for os-vault,
|
||||
os-adr, os-context) — catches capability regression. Functions as "the AI version of TDD"
|
||||
for plugin-type projects: a plugin's eval suite is the thing that must stay green across
|
||||
changes, the same role a test suite plays for application code (see
|
||||
[plugin-factory](plugin-factory.md) for the eval-as-green-command connection).
|
||||
- **d. Skill-lint** (new, cc-os Forgejo issue #72) — catches skill-authoring drift. os-context
|
||||
lints `SKILL.md` files for progressive disclosure on complex tasks and reasonable file
|
||||
sizes, keeping agent context windows lean as the skill corpus grows.
|
||||
|
||||
Together, these four loops are:
|
||||
- the **promotion engine** for [never-ask-twice](never-ask-twice.md) — (b) is the mechanism
|
||||
that actually performs the audit-driven promotion that mechanism depends on;
|
||||
- the **self-evolution channel** for [plugin-factory](plugin-factory.md) — (a), (c), and (d)
|
||||
are exactly the inputs that turn into improvement tickets fed back into factory intake.
|
||||
|
||||
## Open questions
|
||||
|
||||
- ADR-audit criteria: what specifically counts as "stale" and "durable," and cadence.
|
||||
(Mechanical detection is now sketched via the copy-tag-audit pattern above — remaining
|
||||
question is the judgment rubric the audit applies to each virgin ADR.)
|
||||
- Whether ADR audits live in os-context (alongside the existing session-audit skill) or in
|
||||
os-adr (alongside `find`/`create`/`migrate`) — an ownership question, not yet settled.
|
||||
- Whether (a)-(d) should share a common audit-report format so
|
||||
[plugin-factory](plugin-factory.md)'s improvement-ticket generator can consume all four
|
||||
uniformly, or whether each stays bespoke.
|
||||
|
||||
## Sources
|
||||
|
||||
- os-context `audit-sessions` skill (existing biweekly IRL audit)
|
||||
- cc-os Forgejo issue #71 (session-audit rework, expensive-model overuse)
|
||||
- cc-os Forgejo issue #72 (skill-lint)
|
||||
- `plugins/os-vault/eval/`, `plugins/os-adr/eval/`, `plugins/os-context/eval/` (autoresearch
|
||||
eval harnesses)
|
||||
- ADR-0037
|
||||
- 2026-07-16 design session (this doc's origin)
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
# spec and ticket layer
|
||||
|
||||
_Status: settled direction — as of 2026-07-16_
|
||||
_Connects to: [pipeline-stages](pipeline-stages.md), [worktree-parallelism](worktree-parallelism.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
States where specs and tickets live and how a plan becomes an increment `/implement` can
|
||||
consume. Load this before designing `to-spec`, `to-tickets`, or any skill that reads/writes
|
||||
issue-tracker state for os-sdlc.
|
||||
|
||||
## Design
|
||||
|
||||
- **Git issues are the durable spec layer.** Forgejo (via `tea`) or GitHub (via `gh`),
|
||||
resolved per-project by the os-backlog tracker key in `.cc-os/config`
|
||||
(`forgejo:owner/repo`, `github:owner/repo`, or `repo:path` — ADR-0042). Planka is retired;
|
||||
there is no separate os-sdlc storage for specs or tickets.
|
||||
- **Composability constraint (ADR-0037):** os-sdlc consumes `os-backlog` rather than
|
||||
reinventing ticketing. Ticket intake, creation, and listing go through os-backlog's
|
||||
`issue-create`/`issues` CLI wrappers, not a parallel os-sdlc data model.
|
||||
- **Pocock lifecycle mapping**, adapted to the git-issues substrate:
|
||||
- **wayfinder** — big plans, new ideas. Free-form exploration, not yet tracker-shaped.
|
||||
- **grill-with-docs** — sharpens or decomposes a plan further where user direction is
|
||||
genuinely needed (see [never-ask-twice](never-ask-twice.md) for when a question should
|
||||
instead be answered by lookup rather than posed here).
|
||||
- **to-spec** — publishes the sharpened plan to the issue tracker as a spec-bearing issue
|
||||
(or epic-equivalent) — the durable artifact other stages read from.
|
||||
- **to-tickets** — decomposes the spec into feature-specific, independently-implementable
|
||||
increments, each its own issue, tracer-bullet style. Confirmed 2026-07-16: this is
|
||||
Pocock's v1.1 *rename* of `to-issues` ("a spec defines the destination; tickets are the
|
||||
journey"), not a sibling — the leftover `to-issues` skill was removed the same day.
|
||||
- **`/implement`** — consumes exactly one ticket into the [pipeline-stages](pipeline-stages.md)
|
||||
pipeline. One ticket in, one worktree/branch out (see
|
||||
[worktree-parallelism](worktree-parallelism.md)).
|
||||
- The tracker is the single source of truth for spec *and* ticket state — no shadow status
|
||||
file. Stage reports (pipeline-stages) update the issue via comments/labels rather than a
|
||||
separate os-sdlc-owned record.
|
||||
- Spec and ticket content structure is intentionally not fixed yet (see Open questions) —
|
||||
the mapping above fixes *where* things live and *what stage produces them*, not their
|
||||
internal template.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Which Pocock skills (wayfinder, grill-with-docs, to-spec, to-tickets) are adopted
|
||||
near-verbatim vs. adapted for the git-issues substrate vs. skipped entirely.
|
||||
- Whether wayfinder subsumes or sits alongside a DeltaRefinery-style level structure
|
||||
(DeltaRefinery decomposed work into explicit levels; Pocock's wayfinder is looser).
|
||||
- Concrete spec issue template (sections, required fields) and ticket issue template
|
||||
(acceptance criteria shape, tracer-bullet slice size).
|
||||
|
||||
## Sources
|
||||
|
||||
- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
|
||||
- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
|
||||
- `plugins/os-sdlc/OVERVIEW.md`
|
||||
- SecondBrain vault: `matt-pocock-skills-v1-1-changes.md`
|
||||
- `plugins/os-backlog/` (tracker key, `issue-create`/`issues` CLI)
|
||||
- 2026-07-16 design session (this doc's origin)
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
# worktree parallelism
|
||||
|
||||
_Status: direction — as of 2026-07-16_
|
||||
_Connects to: [pipeline-stages](pipeline-stages.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [horizon](horizon.md), [overview](../OVERVIEW.md)_
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines how os-sdlc scopes concurrency: worktree-per-spec, sequential tickets within a spec,
|
||||
parallelism across specs. Load this when designing worktree lifecycle automation or any
|
||||
multi-ticket/multi-spec orchestration for os-sdlc.
|
||||
|
||||
## Design
|
||||
|
||||
- **Worktree-per-spec.** Tickets belonging to one spec run sequentially inside a single
|
||||
worktree — this avoids intra-spec merge conflicts entirely, since only one pipeline run is
|
||||
ever touching that worktree's files at a time.
|
||||
- **Parallelism happens across specs**, not within one. Multiple specs, each with its own
|
||||
worktree and its own sequential ticket queue, can run concurrently to keep overall progress
|
||||
rolling without any single spec's pipeline blocking another's.
|
||||
- **Merge is a human gate in v1** — consistent with [pipeline-stages](pipeline-stages.md)'s
|
||||
final stage. No automated merge choreography yet.
|
||||
- **Tiered isolation ladder** (from the vault taxonomy note): no isolation → single worktree →
|
||||
N parallel worktrees → full sandbox. os-sdlc v1 sits at "single worktree" per spec; a router
|
||||
agent that picks the isolation tier per task is explicitly deferred until a concrete case
|
||||
proves it's needed — not built ahead of that need.
|
||||
- **Known bug — cc-os Forgejo issue #73:** `.cc-os/config` is untracked, so worktrees don't
|
||||
inherit the tracker key, and `os-backlog` issue-create fails inside them. This blocks
|
||||
ticket-intake (stage 1 of [pipeline-stages](pipeline-stages.md)) from working inside a
|
||||
worktree today. The factory needs a native fix — either walking up to the owning repo root
|
||||
to find the config, or provisioning `.cc-os/config` at worktree-creation time.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Whether Pocock's `wayfinder:map` tags should drive merge choreography — check the vault
|
||||
note `matt-pocock-skills-v1-1-changes.md` when designing this; not yet evaluated against
|
||||
os-sdlc's spec/ticket model.
|
||||
- Worktree lifecycle automation: who creates a worktree for a new spec, who cleans it up after
|
||||
merge, and what triggers each.
|
||||
- Branch naming convention for spec-level and (if they ever become worth it) per-ticket
|
||||
branches under a spec branch.
|
||||
|
||||
## Sources
|
||||
|
||||
- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md` (tiered isolation
|
||||
ladder), `matt-pocock-skills-v1-1-changes.md` (wayfinder:map)
|
||||
- cc-os Forgejo issue #73 (`.cc-os/config` untracked, worktree tracker-key inheritance bug)
|
||||
- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
|
||||
- `plugins/os-sdlc/OVERVIEW.md`
|
||||
- 2026-07-16 design session (this doc's origin)
|
||||
Loading…
Reference in New Issue