Split documentation into README, CHANGELOG and DECISIONS #23

Merged

ellen merged 2 commits from docs/restructure into main 2026-09-02 17:42:01 +00:00

Conversation 0 Commits 2 Files changed 14 +644 -206

cloudcli commented 2026-09-02 17:23:46 +00:00

Member

Copy link

Applies the estate-wide three-file documentation convention, matching the reference implementation in valssi/cal-diy.

• README.md — current state: architecture, all six workflow routes and their triggers, the lib/ actions, the label taxonomy in labels.json, and an index of learnings/.
• CHANGELOG.md — 19 entries backfilled from git across PRs #1–#22.
• DECISIONS.md — 17 entries with an initiator label each; Legacy for anything predating this log. Covers label-driven dispatch, org-wide label seeding, comment-context injection and runner-injected credentials.

learnings/ is left as payload — indexed from the README, not rewritten.

Comments in the seven workflow files, both lib/ actions and both label scripts are trimmed to brief statements of what each section does. Verified comment-only — no trigger, job, step, label or expression changed.

One stale README claim corrected: concurrency was described as "not in these workflows, deferred until it matters", but every route does declare a per-issue concurrency: group.

⚠️ Possible live breakage on main, worth checking

plan.yaml, dev.yaml, test.yaml, coordinate.yaml and reflect.yaml all declare a secrets: block directly under on.workflow_call: — confirmed present on main for all five.

An unmerged branch (feat/runner-injested-credentials, commit aebdf0f, diverged at 6ffebe4) diagnoses exactly this: "Forgejo's parser accepts only inputs and outputs there, so all five files were unparseable — every issue event produced five [failures]." If that diagnosis holds, every label route currently fails at parse time.

To be clear about what this is not: this is distinct from the known chronic Forgejo Actions error loop (CreateCommitStatus() … head commit is missing in event payload), which fires as a 15-minute cron burst from schedule:-triggered runs. This one would fire on issue events instead. Two separate problems — fixing this will not quiet that noise.

Not touched here — it is a behaviour fix, out of scope for a docs pass — but it wants verifying against the live instance and, if confirmed, that branch (or an equivalent) merging.

Two related notes:

• The agents/*.md roster is stale: it marks test, coordinate and reflect as status: planned and points at implement.yaml / triage.yaml, but those routes are active as test.yaml / coordinate.yaml / reflect.yaml, and triage.yaml does not exist.
• The runner-injected-credentials entry in DECISIONS.md is labelled as proposed, not deployed — lib/credentials/ does not exist in the tree.

🤖 Generated with Claude Code

Applies the estate-wide three-file documentation convention, matching the reference implementation in `valssi/cal-diy`. - **`README.md`** — current state: architecture, all six workflow routes and their triggers, the `lib/` actions, the label taxonomy in `labels.json`, and an index of `learnings/`. - **`CHANGELOG.md`** — 19 entries backfilled from git across PRs #1–#22. - **`DECISIONS.md`** — 17 entries with an initiator label each; `Legacy` for anything predating this log. Covers label-driven dispatch, org-wide label seeding, comment-context injection and runner-injected credentials. `learnings/` is left as payload — indexed from the README, not rewritten. Comments in the seven workflow files, both `lib/` actions and both label scripts are trimmed to brief statements of what each section does. **Verified comment-only** — no trigger, job, step, label or expression changed. One stale README claim corrected: concurrency was described as *"not in these workflows, deferred until it matters"*, but every route does declare a per-issue `concurrency:` group. ### ⚠️ Possible live breakage on `main`, worth checking `plan.yaml`, `dev.yaml`, `test.yaml`, `coordinate.yaml` and `reflect.yaml` **all declare a `secrets:` block directly under `on.workflow_call:`** — confirmed present on `main` for all five. An unmerged branch (`feat/runner-injested-credentials`, commit `aebdf0f`, diverged at `6ffebe4`) diagnoses exactly this: *"Forgejo's parser accepts only `inputs` and `outputs` there, so all five files were unparseable — every issue event produced five [failures]."* If that diagnosis holds, **every label route currently fails at parse time.** To be clear about what this is *not*: this is **distinct from** the known chronic Forgejo Actions error loop (`CreateCommitStatus() … head commit is missing in event payload`), which fires as a 15-minute cron burst from `schedule:`-triggered runs. This one would fire on **issue events** instead. Two separate problems — fixing this will not quiet that noise. Not touched here — it is a behaviour fix, out of scope for a docs pass — but it wants verifying against the live instance and, if confirmed, that branch (or an equivalent) merging. Two related notes: - The `agents/*.md` roster is stale: it marks `test`, `coordinate` and `reflect` as `status: planned` and points at `implement.yaml` / `triage.yaml`, but those routes are active as `test.yaml` / `coordinate.yaml` / `reflect.yaml`, and `triage.yaml` does not exist. - The runner-injected-credentials entry in `DECISIONS.md` is labelled as **proposed, not deployed** — `lib/credentials/` does not exist in the tree. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

cloudcli added 1 commit 2026-09-02 17:23:46 +00:00

docs: split documentation into README, CHANGELOG and DECISIONS ... 539ecb91a5

README.md describes current state: the architecture, all six workflow routes and their
triggers, the lib/ actions, the label taxonomy and the learnings/ index. CHANGELOG.md
is backfilled from git across PRs #1-#22. DECISIONS.md carries the rationale with an
initiator label per entry; everything predating this log is labelled Legacy rather than
guessed. learnings/ is left as payload and indexed rather than rewritten.

Inline comments in the seven workflow files, both lib/ actions and both label scripts
are trimmed to brief statements of what each section does. Verified comment-only.

One stale README claim corrected: concurrency was described as "not in these workflows,
deferred until it matters", but every route does declare a per-issue concurrency group.

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

cloudcli added 1 commit 2026-09-02 17:31:21 +00:00

docs: widen the AI label to cover independent AI decisions ... 110e042dfb

The label table defined `AI` only as "AI proposed, Ellen approved", which left an
independent AI decision with no correct label. It now covers both. `Ellen` still means
Ellen set the direction.

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

ellen merged commit ea21a83d94 into main 2026-09-02 17:42:01 +00:00

ellen deleted branch docs/restructure 2026-09-02 17:42:01 +00:00

ellen referenced this pull request from a commit 2026-09-02 17:42:02 +00:00

Merge pull request 'Split documentation into README, CHANGELOG and DECISIONS' (#23) from docs/restructure into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

  

agent

coordinate

Summon coordinator on an epic (one-shot; agent removes on pickup)

  

agent

dev

Summon developer (one-shot; agent removes on pickup)

  

agent

plan

Summon planner (one-shot; agent removes on pickup)

  

agent

reflect

Summon reflection agent (one-shot; agent removes on pickup)

  

agent

test

Summon tester on a PR (one-shot; agent removes on pickup)

  

agent

triage

Summon triage (one-shot; agent removes on pickup)

  

ai/off

Agents ignore this issue entirely

  

blocked

night

Queued: waiting for night window

  

blocked

usage

Queued: usage window exhausted (resume time in state comment)

  

loop

1

Dev↔test bounce 1 of 3 at current tier

  

loop

2

Dev↔test bounce 2 of 3 at current tier

  

loop

3

Dev↔test bounce 3 of 3 — cap; next is escalate or needs/human

  

needs/approval

Agent → you: plan awaits approval

  

needs/human

Agent → you: stuck / escalated out (see summary comment)

  

needs/input

Agent → you: blocked on a question only you can answer

  

needs/review

Agent → you: PR passed tests, awaits human review/merge

  

plan/approved

Human approval gate — honored only when applied by APPROVER

  

run/night

Start only inside NIGHT_WINDOW (default 00:00–06:00 Europe/Helsinki)

  

state

blocked

Machine state: blocked (see needs/* or blocked/*)

  

state

building

Machine state (workflow-managed)

  

state

passed

Machine state: tests passed, awaiting merge

  

state

planning

Machine state (workflow-managed)

  

state

testing

Machine state (workflow-managed)

  

tier

fable

Model rung: Fable 5 — HUMAN-APPLIED ONLY

  

tier

haiku

Model rung: Haiku 4.5

  

tier

local

Model rung: local vLLM (no quota)

  

tier

opus

Model rung: Opus 4.8 (hard dev, default plan)

  

tier

sonnet

Model rung: Sonnet 5 (default dev/test)

No labels

agent

coordinate

agent

dev

agent

plan

agent

reflect

agent

test

agent

triage

ai/off

blocked

night

blocked

usage

loop

1

loop

2

loop

3

needs/approval

needs/human

needs/input

needs/review

plan/approved

run/night

state

blocked

state

building

state

passed

state

planning

state

testing

tier

fable

tier

haiku

tier

local

tier

opus

tier

sonnet

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

valssi-public/agent-workflows!23

No description provided.