From 6aa87f97eb3d227768bbd172642e61d6f70c9120 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Mon, 6 Jul 2026 13:43:52 -0600 Subject: [PATCH] Update docs for shipped doc-approval clients and continuous ops skill Add doc-approval platform rows to AGENTS.md, README.md, and design-language.md; replace stale scaffold blocker with shared-core Phase 2 items; document continuous run mode in app-refs-ops skill and multi-thread workflow. Co-authored-by: Cursor --- .agents/skills/app-refs-ops/SKILL.md | 79 ++++++++++++++++++++++++---- .claude/commands/app-refs-ops.md | 79 ++++++++++++++++++++++++---- AGENTS.md | 21 ++++++++ README.md | 14 ++++- docs/design-language.md | 12 +++++ docs/multi-thread-workflow.md | 14 ++--- 6 files changed, 190 insertions(+), 29 deletions(-) diff --git a/.agents/skills/app-refs-ops/SKILL.md b/.agents/skills/app-refs-ops/SKILL.md index 5009cb8..2cb685f 100644 --- a/.agents/skills/app-refs-ops/SKILL.md +++ b/.agents/skills/app-refs-ops/SKILL.md @@ -1,6 +1,6 @@ --- name: "app-refs-ops" -description: "Start or resume the App-References operating model when the user says APP REFS OPS, asks to start app-refs ops/dev work, asks for the ready-ticket worker, PR finisher, or backlog gardener, or wants Codex to pick ready Project 2 work and run the App-References coordination process." +description: "Start or resume the App-References operating model when the user says APP REFS OPS. Runs continuously until no Ready work remains or a hard blocker stops progress — merge green PRs, claim Ready tickets, implement, release, repeat." --- # App-References Ops @@ -23,23 +23,76 @@ The target repo is `traverse-framework/reference-apps` (GitHub slug; product nam Read `docs/traverse-starter-plan.md` and `.specify/memory/constitution.md` before any implementation work. +## Continuous run mode (default) + +`/app-refs-ops` is **not** a single-ticket session. When triggered, run the full ops loop **until idle** — do not stop after one PR, one merge, or one status summary, and do not ask the user "want me to continue?" between tickets. + +### Ops loop + +Repeat until a stop condition (below): + +1. **PR finisher** — inspect open PRs owned by this agent or blocking Ready work; fix CI/review issues; merge when green; rebase if behind `main`. +2. **Release** — after merge: remove `agent:*` label, set Agent → Unassigned, Status → Done, close issue (see Release sequence below). +3. **Ready-ticket worker** — query Ready items; run pre-flight on the next unclaimed ticket; claim; implement; open PR. +4. **Validate** — run applicable local gates; wait for CI; merge when green; go to step 2. + +One issue at a time per agent thread, but **many issues per ops invocation** — keep cycling. + +### Stop conditions (only these) + +Stop reporting only when **all** are true: + +- No open PRs from this ops run need attention (merged or explicitly handed off). +- No Project 2 items remain in `Ready` that pass pre-flight for this agent. +- No fixable CI failures on open PRs you opened this session. + +**Do not stop** merely because one ticket shipped. **Do not pause** for merge approval if CI is green and the user invoked `/app-refs-ops` for autonomous end-to-end execution — merge and continue. + +### When to ask the user + +Ask only for: + +- Product or architecture decisions (`needs-enrico`) +- Merge approval if the user explicitly said not to merge autonomously in this session +- Hard blockers outside this repo (Traverse runtime feature missing, credentials, environment) + +Everything else — claim, implement, PR, CI fix, merge, release — proceed autonomously. + +### Release sequence (after merge) + +```bash +gh issue edit --repo traverse-framework/reference-apps --remove-label "" + +ITEM_ID=$(gh project item-list 2 --owner traverse-framework --format json --limit 300 \ + --jq '.items[] | select(.content.number == ) | .id') + +gh project item-edit --project-id PVT_kwDOEbiBt84BbzAz --id "$ITEM_ID" \ + --field-id PVTSSF_lADOEbiBt84BbzAzzhWjEik --single-select-option-id 8ebf043b + +gh project item-edit --project-id PVT_kwDOEbiBt84BbzAz --id "$ITEM_ID" \ + --field-id PVTSSF_lADOEbiBt84BbzAzzhWg5OQ --single-select-option-id 98236657 + +gh issue close --repo traverse-framework/reference-apps +``` + ## Workflow 1. Read `.specify/memory/constitution.md` before any implementation work. 2. Read `AGENTS.md` and follow the agent coordination rules. 3. Inspect current GitHub and Project 2 state. -4. Prefer finishing existing open PRs before claiming new Ready work. -5. If no active PR needs attention, pick one Ready Project 2 issue. -6. Before work on an issue, run the pre-flight checks from `AGENTS.md`: +4. Enter the **ops loop** above — do not exit after step 10 once; loop until idle. +5. Before work on an issue, run the pre-flight checks from `AGENTS.md`: - issue must not have any `agent:*` label - no remote `*/issue-NNN-*` branch may exist -7. If pre-flight passes, claim the issue: + - Project 2 status must be `Ready` +6. If pre-flight passes, claim the issue: - add your agent label (see Agent Registry in `AGENTS.md`) - set Project 2 `Agent` to your tool - set Project 2 `Status` to `In Progress` -8. Use a dedicated `/issue-NNN-*` branch (see Agent Registry in `AGENTS.md`). -9. Keep work scoped to the claimed issue and the UI-only architecture boundary. -10. Open a dedicated PR with the required sections (Summary, Definition of Done, Validation). +7. Use a dedicated `/issue-NNN-*` branch (see Agent Registry in `AGENTS.md`). +8. Keep work scoped to the claimed issue and the UI-only architecture boundary. +9. Open a dedicated PR with the required sections (Summary, Definition of Done, Validation). +10. Validate, merge when green, release, then **return to step 4** for the next Ready ticket. ## Project 2 IDs @@ -133,9 +186,11 @@ Minimality must never push business logic into the UI, import private Traverse i ## Operating Lanes -- **Ready-ticket worker**: claim one Ready Project 2 issue and implement it end to end. -- **PR finisher**: inspect open PRs, fix CI/review issues, and merge when green. -- **Backlog gardener**: audit Project 2 statuses, labels, blockers, and notes. +All lanes run inside the **continuous ops loop** — none of them end the session after one pass. + +- **PR finisher**: inspect open PRs, fix CI/review issues, merge when green, release linked issues — then pick the next Ready ticket. +- **Ready-ticket worker**: claim one Ready issue, implement end to end, merge, release — then claim the next Ready issue. +- **Backlog gardener**: audit Project 2 statuses, labels, blockers, and notes — only when no Ready work is available or as hygiene between tickets. ## Guardrails @@ -144,5 +199,7 @@ Minimality must never push business logic into the UI, import private Traverse i - Do not claim work already owned by another agent. - Do not broaden scope beyond the issue and the UI-only architecture boundary. - Create follow-up tickets for non-blocking improvements instead of expanding an active slice. +- **Do not stop the ops loop after one ticket** — run until Ready queue is empty or a stop condition applies. +- **Do not ask the user to continue** between tickets during `/app-refs-ops`; that breaks autonomous end-to-end execution. For the full operating model, see `docs/multi-thread-workflow.md`. diff --git a/.claude/commands/app-refs-ops.md b/.claude/commands/app-refs-ops.md index 5009cb8..2cb685f 100644 --- a/.claude/commands/app-refs-ops.md +++ b/.claude/commands/app-refs-ops.md @@ -1,6 +1,6 @@ --- name: "app-refs-ops" -description: "Start or resume the App-References operating model when the user says APP REFS OPS, asks to start app-refs ops/dev work, asks for the ready-ticket worker, PR finisher, or backlog gardener, or wants Codex to pick ready Project 2 work and run the App-References coordination process." +description: "Start or resume the App-References operating model when the user says APP REFS OPS. Runs continuously until no Ready work remains or a hard blocker stops progress — merge green PRs, claim Ready tickets, implement, release, repeat." --- # App-References Ops @@ -23,23 +23,76 @@ The target repo is `traverse-framework/reference-apps` (GitHub slug; product nam Read `docs/traverse-starter-plan.md` and `.specify/memory/constitution.md` before any implementation work. +## Continuous run mode (default) + +`/app-refs-ops` is **not** a single-ticket session. When triggered, run the full ops loop **until idle** — do not stop after one PR, one merge, or one status summary, and do not ask the user "want me to continue?" between tickets. + +### Ops loop + +Repeat until a stop condition (below): + +1. **PR finisher** — inspect open PRs owned by this agent or blocking Ready work; fix CI/review issues; merge when green; rebase if behind `main`. +2. **Release** — after merge: remove `agent:*` label, set Agent → Unassigned, Status → Done, close issue (see Release sequence below). +3. **Ready-ticket worker** — query Ready items; run pre-flight on the next unclaimed ticket; claim; implement; open PR. +4. **Validate** — run applicable local gates; wait for CI; merge when green; go to step 2. + +One issue at a time per agent thread, but **many issues per ops invocation** — keep cycling. + +### Stop conditions (only these) + +Stop reporting only when **all** are true: + +- No open PRs from this ops run need attention (merged or explicitly handed off). +- No Project 2 items remain in `Ready` that pass pre-flight for this agent. +- No fixable CI failures on open PRs you opened this session. + +**Do not stop** merely because one ticket shipped. **Do not pause** for merge approval if CI is green and the user invoked `/app-refs-ops` for autonomous end-to-end execution — merge and continue. + +### When to ask the user + +Ask only for: + +- Product or architecture decisions (`needs-enrico`) +- Merge approval if the user explicitly said not to merge autonomously in this session +- Hard blockers outside this repo (Traverse runtime feature missing, credentials, environment) + +Everything else — claim, implement, PR, CI fix, merge, release — proceed autonomously. + +### Release sequence (after merge) + +```bash +gh issue edit --repo traverse-framework/reference-apps --remove-label "" + +ITEM_ID=$(gh project item-list 2 --owner traverse-framework --format json --limit 300 \ + --jq '.items[] | select(.content.number == ) | .id') + +gh project item-edit --project-id PVT_kwDOEbiBt84BbzAz --id "$ITEM_ID" \ + --field-id PVTSSF_lADOEbiBt84BbzAzzhWjEik --single-select-option-id 8ebf043b + +gh project item-edit --project-id PVT_kwDOEbiBt84BbzAz --id "$ITEM_ID" \ + --field-id PVTSSF_lADOEbiBt84BbzAzzhWg5OQ --single-select-option-id 98236657 + +gh issue close --repo traverse-framework/reference-apps +``` + ## Workflow 1. Read `.specify/memory/constitution.md` before any implementation work. 2. Read `AGENTS.md` and follow the agent coordination rules. 3. Inspect current GitHub and Project 2 state. -4. Prefer finishing existing open PRs before claiming new Ready work. -5. If no active PR needs attention, pick one Ready Project 2 issue. -6. Before work on an issue, run the pre-flight checks from `AGENTS.md`: +4. Enter the **ops loop** above — do not exit after step 10 once; loop until idle. +5. Before work on an issue, run the pre-flight checks from `AGENTS.md`: - issue must not have any `agent:*` label - no remote `*/issue-NNN-*` branch may exist -7. If pre-flight passes, claim the issue: + - Project 2 status must be `Ready` +6. If pre-flight passes, claim the issue: - add your agent label (see Agent Registry in `AGENTS.md`) - set Project 2 `Agent` to your tool - set Project 2 `Status` to `In Progress` -8. Use a dedicated `/issue-NNN-*` branch (see Agent Registry in `AGENTS.md`). -9. Keep work scoped to the claimed issue and the UI-only architecture boundary. -10. Open a dedicated PR with the required sections (Summary, Definition of Done, Validation). +7. Use a dedicated `/issue-NNN-*` branch (see Agent Registry in `AGENTS.md`). +8. Keep work scoped to the claimed issue and the UI-only architecture boundary. +9. Open a dedicated PR with the required sections (Summary, Definition of Done, Validation). +10. Validate, merge when green, release, then **return to step 4** for the next Ready ticket. ## Project 2 IDs @@ -133,9 +186,11 @@ Minimality must never push business logic into the UI, import private Traverse i ## Operating Lanes -- **Ready-ticket worker**: claim one Ready Project 2 issue and implement it end to end. -- **PR finisher**: inspect open PRs, fix CI/review issues, and merge when green. -- **Backlog gardener**: audit Project 2 statuses, labels, blockers, and notes. +All lanes run inside the **continuous ops loop** — none of them end the session after one pass. + +- **PR finisher**: inspect open PRs, fix CI/review issues, merge when green, release linked issues — then pick the next Ready ticket. +- **Ready-ticket worker**: claim one Ready issue, implement end to end, merge, release — then claim the next Ready issue. +- **Backlog gardener**: audit Project 2 statuses, labels, blockers, and notes — only when no Ready work is available or as hygiene between tickets. ## Guardrails @@ -144,5 +199,7 @@ Minimality must never push business logic into the UI, import private Traverse i - Do not claim work already owned by another agent. - Do not broaden scope beyond the issue and the UI-only architecture boundary. - Create follow-up tickets for non-blocking improvements instead of expanding an active slice. +- **Do not stop the ops loop after one ticket** — run until Ready queue is empty or a stop condition applies. +- **Do not ask the user to continue** between tickets during `/app-refs-ops`; that breaks autonomous end-to-end execution. For the full operating model, see `docs/multi-thread-workflow.md`. diff --git a/AGENTS.md b/AGENTS.md index be8c3d3..fc84ac6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,18 @@ This repo is **UI-only**. Traverse runtime and business logic live outside this | Linux (GTK4 + Rust) | Shipped | `apps/traverse-starter/linux-gtk/` | | CLI (Rust) | Shipped | `apps/traverse-starter/cli-rust/` | +### doc-approval clients (Phase 1 submitter — shipped) + +| Platform | Status | Path | +|---|---|---| +| Web (React + TypeScript) | Shipped | `apps/doc-approval/web-react/` | +| iOS (SwiftUI) | Shipped | `apps/doc-approval/ios-swift/` | +| macOS (SwiftUI + AppKit) | Shipped | `apps/doc-approval/macos-swift/` | +| Android (Jetpack Compose) | Shipped | `apps/doc-approval/android-compose/` | +| Windows (WinUI 3) | Shipped | `apps/doc-approval/windows-winui/` | +| Linux (GTK4 + Rust) | Shipped | `apps/doc-approval/linux-gtk/` | +| CLI (Rust) | Shipped | `apps/doc-approval/cli-rust/` | + ### Ready to claim (query live board) ```bash @@ -30,6 +42,7 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \ - **Web SSE refactor** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on Traverse #525, #526, #527 - **Platform SSE upgrade (Phase 2)** — iOS/macOS/Android/Windows/Linux/CLI Phase 1 scaffolds use HTTP polling; SSE blocked on same Traverse issues +- **doc-approval shared core** ([#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — extract shared Swift/Rust client packages; blocked on Phase 2 SSE / shared crate design Update this section when a PR changes platform status (see PR template checklist). @@ -45,6 +58,14 @@ apps/ windows-winui/ # WinUI 3 Windows client linux-gtk/ # GTK4 + Rust Linux client cli-rust/ # Rust CLI client + doc-approval/ + web-react/ # React submitter UI + ios-swift/ # SwiftUI iOS client + macos-swift/ # SwiftUI macOS client + android-compose/ # Jetpack Compose Android client + windows-winui/ # WinUI 3 Windows client + linux-gtk/ # GTK4 + Rust Linux client + cli-rust/ # Rust CLI client .agents/skills/ app-refs-ops/ # Ops skill for Project 2 work .specify/memory/ # Constitution and governing principles diff --git a/README.md b/README.md index ae9d419..33031ac 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,18 @@ All clients are UI-only shells — they invoke the runtime and render structured | Linux (GTK4 + Rust) | Shipped | [`apps/traverse-starter/linux-gtk/`](apps/traverse-starter/linux-gtk/) | | CLI (Rust) | Shipped | [`apps/traverse-starter/cli-rust/`](apps/traverse-starter/cli-rust/) | +### doc-approval (Phase 1 submitter) + +| Platform | Status | Path | +|---|---|---| +| Web (React + TypeScript) | Shipped | [`apps/doc-approval/web-react/`](apps/doc-approval/web-react/) | +| iOS (SwiftUI) | Shipped | [`apps/doc-approval/ios-swift/`](apps/doc-approval/ios-swift/) | +| macOS (SwiftUI + AppKit) | Shipped | [`apps/doc-approval/macos-swift/`](apps/doc-approval/macos-swift/) | +| Android (Jetpack Compose) | Shipped | [`apps/doc-approval/android-compose/`](apps/doc-approval/android-compose/) | +| Windows (WinUI 3) | Shipped | [`apps/doc-approval/windows-winui/`](apps/doc-approval/windows-winui/) | +| Linux (GTK4 + Rust) | Shipped | [`apps/doc-approval/linux-gtk/`](apps/doc-approval/linux-gtk/) | +| CLI (Rust) | Shipped | [`apps/doc-approval/cli-rust/`](apps/doc-approval/cli-rust/) | + ## Development ```bash @@ -100,4 +112,4 @@ Active blockers on [Project 2](https://github.com/orgs/traverse-framework/projec - **SSE state subscription** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on [Traverse #525](https://github.com/traverse-framework/Traverse/issues/525), [#526](https://github.com/traverse-framework/Traverse/issues/526), [#527](https://github.com/traverse-framework/Traverse/issues/527). All platform clients inherit this blocker for Phase 2 SSE upgrade. - **meeting-notes web-react** ([#57](https://github.com/traverse-framework/reference-apps/issues/57)) — second domain app (list-type output); blocked pending runtime capability work. -- **doc-approval scaffolds** ([#65](https://github.com/traverse-framework/reference-apps/issues/65)–[#73](https://github.com/traverse-framework/reference-apps/issues/73)) — submitter + approver surfaces across Web, iOS, macOS, Android, Windows, Linux, CLI, and shared core packages; blocked pending domain capability registration in Traverse. +- **doc-approval shared core** ([#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — extract shared Swift/Rust client packages for iOS/macOS and linux-gtk/cli-rust; Phase 2 work blocked on SSE and crate design. diff --git a/docs/design-language.md b/docs/design-language.md index f760d0f..d330985 100644 --- a/docs/design-language.md +++ b/docs/design-language.md @@ -69,6 +69,18 @@ The UI renders these fields exactly as the runtime provides them — never compu | Linux (GTK4 + Rust) | `apps/traverse-starter/linux-gtk/` | Shipped | | CLI (Rust) | `apps/traverse-starter/cli-rust/` | Shipped | +### doc-approval (Phase 1 submitter) + +| Platform | Path | Status | +|---|---|---| +| Web (React) | `apps/doc-approval/web-react/` | Shipped | +| iOS (SwiftUI) | `apps/doc-approval/ios-swift/` | Shipped | +| macOS (SwiftUI + AppKit) | `apps/doc-approval/macos-swift/` | Shipped | +| Android (Jetpack Compose) | `apps/doc-approval/android-compose/` | Shipped | +| Windows (WinUI 3) | `apps/doc-approval/windows-winui/` | Shipped | +| Linux (GTK4 + Rust) | `apps/doc-approval/linux-gtk/` | Shipped | +| CLI (Rust) | `apps/doc-approval/cli-rust/` | Shipped | + New platform clients must link to this doc in their issue Definition of Done. ## Governance diff --git a/docs/multi-thread-workflow.md b/docs/multi-thread-workflow.md index 74342b6..f7cc19f 100644 --- a/docs/multi-thread-workflow.md +++ b/docs/multi-thread-workflow.md @@ -76,13 +76,15 @@ Use this short trigger when you want Codex to start or resume the App-References APP REFS OPS ``` -When Enrico says `APP REFS OPS`, Codex should: +When Enrico says `APP REFS OPS`, the agent should run the **continuous ops loop** (see `.agents/skills/app-refs-ops/SKILL.md`) until idle: -- Start or resume the **ready-ticket worker**: pick one Ready Project 2 ticket, follow `AGENTS.md`, claim it, set `In Progress`, implement on one branch, open one PR. -- Start or resume the **PR finisher**: inspect open PRs, fix CI/review issues, merge green PRs, update linked issues and Project 2 state. -- Start or resume the **backlog gardener**: audit Project 2 statuses, labels, blockers, and notes; ensure items have the right status; create missing tickets with full Definition of Done. -- Do all feasible work autonomously. Ask only when a product or architecture decision requires Enrico. -- Run lean: filtered Project 2 queries, bounded command output, focused diffs, summarized CI results. +- **PR finisher** → merge green PRs, release linked issues +- **Ready-ticket worker** → claim, implement, PR, merge, release — then pick the next Ready ticket +- **Backlog gardener** → only when no Ready work is available + +Do **not** stop after one ticket or ask to continue between tickets. Ask only for product/architecture decisions or hard external blockers. + +Run lean: filtered Project 2 queries, bounded command output, focused diffs, summarized CI results. ## Starter Prompts