chore: trim sprint and using-archeflow skills for context efficiency

sprint: 302 -> 164 lines (removed pseudocode, redundant tables, Prerequisites)
using-archeflow: 185 -> 55 lines (removed archetypes table, PDCA diagram, progress
indicators, dry-run example, full skills reference)
This commit is contained in:
2026-04-06 20:43:23 +02:00
parent 1baaa79946
commit 55de51aabe
2 changed files with 98 additions and 365 deletions

View File

@@ -20,16 +20,10 @@ This is the **primary operational mode** for ArcheFlow in multi-project workspac
Use it when the user says "run the sprint", "work the queue", "go autonomous", or Use it when the user says "run the sprint", "work the queue", "go autonomous", or
invokes `af-sprint`. invokes `af-sprint`.
Do NOT use `archeflow:run` for individual tasks within a sprint the sprint runner Do NOT use `archeflow:run` for individual tasks within a sprint -- the sprint runner
handles task dispatch internally, using `archeflow:run` only when a task warrants handles task dispatch internally, using `archeflow:run` only when a task warrants
full PDCA orchestration. full PDCA orchestration.
## Prerequisites
- `docs/orchestra/queue.json` — task queue (managed by `./scripts/ws`)
- `./scripts/ws` — workspace CLI for queue operations
- Each project is a separate git repo under the workspace root
## Invocation ## Invocation
``` ```
@@ -46,21 +40,12 @@ af-sprint --project writing.colette # Only process items for this project
### Step 0: Orient ### Step 0: Orient
```bash Load queue from `docs/orchestra/queue.json`. Check mode (`AUTONOM` / `ATTENDED` / `PAUSED`).
# Load queue and workspace state Show one-line status: `sprint: AUTONOM | 7 pending (1xP0, 1xP2, 5xP3) | 4 slots`
QUEUE=$(cat docs/orchestra/queue.json)
MODE=$(echo "$QUEUE" | jq -r '.mode')
```
Check mode: - `AUTONOM` -- proceed without asking
- `AUTONOM` → proceed without asking - `ATTENDED` -- show plan, wait for user approval before each batch
- `ATTENDED` → show plan, wait for user approval before each batch - `PAUSED` -- report status only, do not start tasks
- `PAUSED` → report status only, do not start tasks
Show one-line status:
```
sprint: AUTONOM · 7 pending (1×P0, 1×P2, 5×P3) · 4 slots
```
### Step 1: Select Batch ### Step 1: Select Batch
@@ -69,234 +54,111 @@ Pick tasks for the next batch. Rules:
1. **Priority cascade**: P0 first, then P1, then P2. Never start P3 unless user explicitly includes it. 1. **Priority cascade**: P0 first, then P1, then P2. Never start P3 unless user explicitly includes it.
2. **Dependency check**: Skip tasks whose `depends_on` items aren't all `completed`. 2. **Dependency check**: Skip tasks whose `depends_on` items aren't all `completed`.
3. **One agent per project**: Never run two tasks on the same project simultaneously. 3. **One agent per project**: Never run two tasks on the same project simultaneously.
4. **Cost-aware concurrency**: 4. **Cost-aware concurrency**: L/XL tasks (expensive) max 2 concurrent. Fill remaining slots with S/M tasks. Target mix: 1-2 expensive + 2-3 cheap.
- Estimate task cost from `estimate` field: S=cheap, M=moderate, L=expensive, XL=very expensive
- **Expensive tasks** (L, XL): max 2 concurrent
- **Cheap tasks** (S, M): fill remaining slots
- Target mix: 1-2 expensive + 2-3 cheap = 4-5 total
5. **Slot limit**: Never exceed `--slots` (default 4). 5. **Slot limit**: Never exceed `--slots` (default 4).
```python
# Pseudocode for batch selection
batch = []
used_projects = set()
expensive_count = 0
for priority in ["P0", "P1", "P2"]:
for task in queue_items(priority, status="pending"):
if len(batch) >= MAX_SLOTS:
break
if task.project in used_projects:
continue # One agent per project
if not deps_satisfied(task):
continue
if task.estimate in ("L", "XL"):
if expensive_count >= 2:
continue
expensive_count += 1
batch.append(task)
used_projects.add(task.project)
```
### Step 2: Assess and Dispatch ### Step 2: Assess and Dispatch
For each task in the batch, decide the execution strategy: For each task in the batch, decide the execution strategy:
| Signal | Strategy | What happens | | Signal | Strategy |
|--------|----------|-------------| |--------|----------|
| Estimate S, clear scope | **Direct** | Spawn Agent() with task description, no orchestration | | Estimate S, clear scope | **Direct** -- Agent with task description, no orchestration |
| Estimate M, multi-file | **Direct+** | Spawn Agent() with task + "read code first, run tests after" | | Estimate M, multi-file | **Direct+** -- Agent with "read code first, run tests after" |
| Estimate L/XL, code | **Feature-dev style** | Agent explores implements self-reviews (see below) | | Estimate L/XL, code | **Feature-dev** -- Agent explores, plans, implements, tests, self-reviews, commits |
| Estimate L/XL, writing | **PDCA** | Use af-run with writing domain archetypes | | Estimate L/XL, writing | **PDCA** -- Use af-run with writing domain archetypes |
| Task contains "validate", "test", "lint", "check" | **Direct** | Cheap analytical task, no orchestration | | validate/test/lint/check tasks | **Direct** -- cheap analytical, no orchestration |
| Task contains "review", "audit", "security" | **Review** | Spawn Guardian + relevant reviewers only | | review/audit/security tasks | **Review** -- spawn Guardian + relevant reviewers only |
### L/XL Code Task Template (feature-dev style) ### L/XL Code Task Template
For complex code tasks, give the agent a structured process instead of PDCA: Give the agent a structured process:
``` ```
Agent( Agent(prompt: "You are working on <project> at <path>. Task: <description>
description: "<project>: <task-short>",
prompt: "You are working on project <project> at <path>.
Task: <task description>
Follow this process: 1. EXPLORE: Read CLAUDE.md, docs/status.md, relevant source files.
1. EXPLORE: Read CLAUDE.md, docs/status.md, and the relevant source files. 2. PLAN: Identify files to change, write brief plan (what, where, why).
Understand existing patterns before writing anything. 3. IMPLEMENT: Follow existing code patterns strictly.
2. PLAN: Identify 2-3 files to change. Write a brief plan (what, where, why). 4. TEST: Run project test suite, fix failures.
If ambiguous, list your assumptions. 5. SELF-REVIEW: Re-read diff -- error handling, protocol compliance, test coverage.
3. IMPLEMENT: Make the changes. Follow existing code patterns strictly.
4. TEST: Run the project's test suite. Fix any failures.
5. SELF-REVIEW: Before committing, re-read your diff. Check:
- Error handling: what happens when this fails?
- Protocol compliance: am I using the right function signatures?
- Tests: did I test the important paths?
6. COMMIT + PUSH: Conventional commits, signed, pushed. 6. COMMIT + PUSH: Conventional commits, signed, pushed.
<standard rules> STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED")
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED"
)
``` ```
This gives the agent feature-dev's structured exploration without the multi-agent overhead. ### Agent Spawn Template
For writing/research L/XL tasks, use af-run instead — archetypes add value where linters don't exist.
**Agent spawn template:** Spawn ALL batch agents in a **single message** (parallel execution). Each agent gets:
For each task in the batch, spawn an Agent in the SAME message (parallel dispatch):
``` ```
Agent( Agent(
description: "<project>: <task-short>", description: "<project>: <task-short>",
prompt: "You are working on project <project> at <path>. prompt: "You are working on <project> at <path>. Task: <description>
Task: <task description>
<notes if any>
Rules: Rules:
- Read the project's CLAUDE.md first - Read the project's CLAUDE.md first
- Commit with: git -c user.signingkey=/home/c/.ssh/id_ed25519_dev.pub commit - Commit: git -c user.signingkey=/home/c/.ssh/id_ed25519_dev.pub commit
- NO Co-Authored-By trailers - NO Co-Authored-By trailers, conventional commits
- Conventional commits - Push: GIT_SSH_COMMAND='ssh -i /home/c/.ssh/id_ed25519_dev -o IdentitiesOnly=yes' git push origin main
- Push when done: GIT_SSH_COMMAND='ssh -i /home/c/.ssh/id_ed25519_dev -o IdentitiesOnly=yes' git push origin main
- Run tests if the project has them - Run tests if the project has them
- Report: what you did, what changed, any blockers - Report: what you did, what changed, any blockers
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED", STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED",
subagent_type: "general-purpose", isolation: "worktree" # Only for L/XL tasks; S/M run directly
isolation: "worktree" # Only for L/XL tasks; S/M tasks run directly
) )
``` ```
**CRITICAL: Spawn all batch agents in a SINGLE message.** This enables parallel execution.
Do not spawn them sequentially.
### Step 3: Mark Running ### Step 3: Mark Running
After spawning, update the queue: Update the queue after spawning:
```bash ```bash
# For each spawned task ./scripts/ws start <task-id> # or update queue.json status to "running" directly
./scripts/ws start <task-id> # or manually update queue.json status to "running"
```
If `./scripts/ws start` doesn't exist, update queue.json directly:
```python
task["status"] = "running"
# Write back to docs/orchestra/queue.json
``` ```
### Step 4: Collect Results ### Step 4: Collect Results
As agents complete, process their results: Parse status token from agent output. Based on status:
- `DONE` -- mark completed, note result
- `DONE_WITH_CONCERNS` -- mark completed, log concerns for user review
- `NEEDS_CONTEXT` -- mark pending, add concern to notes, skip for now
- `BLOCKED` -- mark failed, add blocker to notes
1. **Parse status token** from agent output (last line: `STATUS: DONE|...`) Update: `./scripts/ws done <task-id> -r "<summary>"` or `./scripts/ws fail <task-id> -r "<reason>"`
2. **Based on status**:
- `DONE` → mark completed, note result
- `DONE_WITH_CONCERNS` → mark completed, log concerns for user review
- `NEEDS_CONTEXT` → mark pending, add concern to notes, skip for now
- `BLOCKED` → mark failed, add blocker to notes
3. **Update queue**:
```bash
./scripts/ws done <task-id> -r "<summary of what was done>"
# or
./scripts/ws fail <task-id> -r "<reason>"
```
### Step 5: Report and Loop ### Step 5: Report and Loop
After batch completes, show sprint status: Show batch status, then **immediately select next batch** (no user prompt in AUTONOM mode):
``` ```
── Sprint Batch 1 ────────────────────────────── -- Sprint Batch 1 --------------------------------------------------
writing.colette fanout run done (45s) + writing.colette fanout run done (45s)
book.3sets validation done (30s) + book.3sets validation done (30s)
book.sos meta-book concept needs_context (missing outline) ! book.sos meta-book concept needs_context
tool.archeflow af-review mode done (60s) + tool.archeflow af-review mode done (60s)
Queue: 3 completed, 1 blocked, 3 remaining Queue: 3 completed, 1 blocked, 3 remaining
Next batch: 2 items ready --------------------------------------------------------------------
────────────────────────────────────────────────
``` ```
Then **immediately select and dispatch the next batch** (Step 1). Don't wait for user input in AUTONOM mode.
### Step 6: Sprint Complete ### Step 6: Sprint Complete
When no more tasks are schedulable (all done, blocked, or P3-only): When no more tasks are schedulable:
1. Update `docs/control-center.md` Handoff section 1. Update `docs/control-center.md` Handoff section
2. Run `./scripts/ws log --summary "<sprint summary>"` if available 2. Run `./scripts/ws log --summary "<sprint summary>"`
3. Show final sprint report: 3. Show final report with duration, tasks completed/blocked/remaining, projects touched, commits
```
── Sprint Complete ─────────────────────────────
Duration: 12 min
Tasks: 5 completed, 1 blocked, 1 remaining (P3)
Projects touched: 4
Commits: 7
────────────────────────────────────────────────
```
--- ---
## Mode Behavior ## Mode Behavior
### AUTONOM | Mode | Dispatch | Between batches | Stops for |
- Dispatch immediately, no user confirmation |------|----------|----------------|-----------|
- Commit + push after each agent completes | **AUTONOM** | Immediate | One-line status, no pause | BLOCKED or budget exhaustion |
- Only pause for BLOCKED tasks or budget exhaustion | **ATTENDED** | Show batch, wait for approval | Show results, ask "Continue? [y/n/edit]" | User decision |
- Report between batches (one-line status) | **PAUSED** | No dispatch | -- | Always (status display only) |
### ATTENDED
- Show the selected batch before dispatching
- Wait for user to approve: "Proceed with this batch? [y/n]"
- After each batch, show results and ask: "Continue to next batch? [y/n/edit]"
- "edit" lets the user reprioritize before next batch
### PAUSED
- Show queue status only
- Do not dispatch any agents
- Useful for reviewing state between sessions
---
## When to Use ArcheFlow Orchestration Within Sprint
Most sprint tasks should be **direct agent dispatch** (no PDCA/pipeline overhead).
Only escalate to full orchestration when:
| Signal | Action |
|--------|--------|
| Task is S/M, clear scope, single project | Direct dispatch |
| Task is L/XL | Use pipeline or PDCA strategy |
| Task mentions "security", "auth", "encryption" | Add Guardian review |
| Task is a review/audit | Spawn reviewers only (af-review mode) |
| Task failed in a previous sprint | Escalate to PDCA with Explorer |
The sprint runner's job is **throughput**, not perfection. Ship fast, fix forward.
---
## Integration with Existing Tools
| Tool | How sprint uses it |
|------|-------------------|
| `./scripts/ws next` | Get next schedulable task |
| `./scripts/ws done <id>` | Mark task completed |
| `./scripts/ws fail <id>` | Mark task failed |
| `./scripts/ws orient` | Initial workspace overview |
| `./scripts/ws validate` | Pre-flight queue validation |
| `git` per project | Commit + push after each agent |
| `archeflow:run` | Only for L/XL tasks needing PDCA |
---
## Error Recovery ## Error Recovery
- **Agent crashes mid-task**: Mark task as `failed`, add error to notes, continue with next batch - **Agent crash**: Mark `failed`, continue with next batch
- **Git push fails**: Log the error, do NOT retry. User will handle push conflicts manually. - **Git push fails**: Log error, do NOT retry -- user handles conflicts
- **Queue file corrupted**: Run `./scripts/ws validate`. If invalid, stop sprint and report. - **Queue corrupted**: Run `./scripts/ws validate`, stop if invalid
- **Budget exceeded**: Stop sprint, report remaining tasks and estimated cost. - **Budget exceeded**: Stop sprint, report remaining tasks and estimated cost
- **All tasks blocked**: Report dependency graph, suggest which blockers to resolve first. - **All blocked**: Report dependency graph, suggest which blockers to resolve first

View File

@@ -5,180 +5,51 @@ description: Use at session start when implementing features, reviewing code, de
# ArcheFlow -- Active # ArcheFlow -- Active
Multi-agent orchestration using archetypal roles and PDCA quality cycles. On activation, print ONE line then proceed silently:
## Session Start
On activation, print ONE line:
``` ```
archeflow v0.7.0 · 25 skills · <domain> domain archeflow v0.7.0 · 25 skills · <domain> domain
``` ```
Where `<domain>` is auto-detected: `writing` if `colette.yaml` exists, `research` if paper/thesis files exist, `code` otherwise. Then proceed silently — no further announcement unless `archeflow:run` is invoked. Domain auto-detected: `writing` if `colette.yaml` exists, `research` if paper/thesis files, `code` otherwise.
During runs, follow the `archeflow:presence` skill for output format: show outcomes not mechanics, one line per phase, value at the end. ## When to Use What
## IMPORTANT: When to Use What | Need | Command | When |
|------|---------|------|
### Use `/af-sprint` (primary mode) when: | **Work the queue** | `/af-sprint` | Multiple tasks pending across projects, "run the sprint" |
- User says "run the sprint", "work the queue", "go autonomous" | **Deep orchestration** | `/af-run` | Writing/research tasks, security-sensitive code, complex multi-module refactors |
- Multiple tasks are pending across projects | **Code review** | `/af-review` | Review diff/branch/commits before merging, security-sensitive changes |
- The workspace queue (docs/orchestra/queue.json) has pending items | **Single feature** | `feature-dev` or direct | Clear scope, one project -- no orchestration needed |
### Use `/af-review` when:
- User wants to review code before merging
- A diff, branch, or commit range needs quality check
- Security-sensitive changes need Guardian analysis
### Use `/af-run` (deep orchestration) when:
- **Writing/research tasks** -- archetypes add value where linters don't exist
- **Security-sensitive code changes** -- auth, encryption, API keys
- **Complex multi-module refactors** with unclear approach
### Do NOT use ArcheFlow for:
- **Single-feature code development** -- use `feature-dev` plugin or work directly
- **Simple fixes** -- just do them
- **Questions, exploration, reading** -- no code changes needed
Choose the workflow based on risk:
| Signal | Workflow | Command |
|--------|----------|---------|
| Small fix, low risk, single concern | `fast` | Creator --> Maker --> Guardian |
| Feature, multiple files, moderate risk | `standard` | Explorer + Creator --> Maker --> Guardian + Skeptic + Sage |
| Security-sensitive, breaking changes, public API | `thorough` | Explorer + Creator --> Maker --> All 4 reviewers |
## When to Skip ArcheFlow ## When to Skip ArcheFlow
Do NOT use ArcheFlow for these -- just do them directly: Do NOT use for: single-line fixes, questions, reading/exploring, config tweaks, git ops.
- Single-line fixes, typos, formatting ## Workflow Selection
- Answering questions (no code changes)
- Reading/exploring code without making changes
- Config changes to a single file
- Git operations (commit, push, branch)
**Mini-Reflect fallback:** Even when skipping ArcheFlow, apply a quick reflection for non-trivial single-file changes: (1) restate what you're changing, (2) name one assumption, (3) check if it could break anything. This takes ~10 seconds and catches misunderstandings before they become commits. | Signal | Workflow | Pipeline |
|--------|----------|----------|
## Archetypes | Small fix, low risk | `fast` | Creator --> Maker --> Guardian |
| Feature, multi-file, moderate risk | `standard` | Explorer + Creator --> Maker --> Guardian + Skeptic + Sage |
| Archetype | Avatar | Virtue | Shadow | Phase | | Security, breaking changes, public API | `thorough` | Explorer + Creator --> Maker --> All 4 reviewers |
|-----------|--------|--------|--------|-------|
| **Explorer** | 🔍 | Contextual Clarity | Rabbit Hole | Plan |
| **Creator** | 🏗️ | Decisive Framing | Over-Architect | Plan |
| **Maker** | ⚒️ | Execution Discipline | Rogue | Do |
| **Guardian** | 🛡️ | Threat Intuition | Paranoid | Check |
| **Skeptic** | 🤔 | Assumption Surfacing | Paralytic | Check |
| **Trickster** | 🃏 | Adversarial Creativity | False Alarm | Check |
| **Sage** | 📚 | Maintainability Judgment | Bureaucrat | Check |
## PDCA Cycle
```
Plan --> Explorer researches, Creator proposes
Do --> Maker implements in isolated worktree
Check --> Reviewers assess in parallel (approve/reject)
Act --> All approved? Merge. Issues? Cycle back to Plan.
```
## Progress Indicators
During orchestration, emit phase markers so the user can track progress:
```
--- ArcheFlow: <task> -------------------------
Workflow: standard (2 cycles max)
🔍 [Plan] Explorer researching... done (35s)
🏗️ [Plan] Creator designing proposal... done (25s, confidence: 0.8)
⚒️ [Do] Maker implementing... done (90s, 4 files, 8 tests)
🛡️ [Check] Guardian reviewing... APPROVED
🤔 [Check] Skeptic challenging... APPROVED (1 INFO)
📚 [Check] Sage reviewing... APPROVED
[Act] All approved -- merging... merged to main
--- Complete: 3m 10s, 1 cycle -----------------
```
Update each line as agents complete. This gives the user real-time visibility without interrupting the flow.
## Dry-Run Mode
When the user asks "what would ArcheFlow do?" or uses `--dry-run`, show the plan without executing:
```
Dry run for: "Add JWT authentication"
Workflow: standard (2 cycles)
Agents: 🔍 Explorer --> 🏗️ Creator --> ⚒️ Maker --> 🛡️ Guardian + 🤔 Skeptic + 📚 Sage
Est. agents: 6 per cycle, 12 max
Worktree: yes (isolated branch)
Proceed? [y/n]
```
## Quick Start
When the user gives an implementation task:
1. Assess: does this need ArcheFlow? (see criteria above)
2. If yes: load `archeflow:orchestration` skill
3. Pick workflow (fast/standard/thorough)
4. Execute the PDCA steps from the orchestration skill
5. Emit progress indicators throughout (see above)
## Available Commands ## Available Commands
| Command | What it does | | Command | What it does |
|---------|-------------| |---------|-------------|
| `archeflow:run` | Automated PDCA loop -- single command to orchestrate a full run | | `/af-sprint` | Queue-driven parallel agent runner (primary mode) |
| `archeflow:orchestration` | Load manual PDCA execution guide | | `/af-run <task>` | PDCA orchestration loop (`--dry-run`, `--start-from`, `--workflow`) |
| `archeflow:shadow-detection` | Load shadow monitoring rules | | `/af-review` | Guardian-led code review on diff/branch/range |
| `archeflow:autonomous-mode` | Load autonomous/overnight session protocol | | `/af-status` | Current run state, active agents, findings |
| `archeflow:status` | Show current orchestration state (phase, cycle, active agents) | | `/af-report` | Full process report for a run |
| `archeflow:history` | Show past orchestration summaries from `.archeflow/session-log.md` | | `/af-init` | Initialize ArcheFlow in a project |
| `/af-score` | Archetype effectiveness scores |
| `/af-memory` | Cross-run lesson memory |
| `/af-fanout` | Colette book fanout via agents |
| `/af-dag` | DAG of current/last run |
### `archeflow:status` ## Mini-Reflect Fallback
Read `.archeflow/state.json` (if exists) and report:
- Current task, phase, and cycle
- Active agents and their status
- Findings so far (by severity)
- Time elapsed
### `archeflow:history` Even when skipping ArcheFlow, apply for non-trivial changes:
Read `.archeflow/session-log.md` and show the last 5 orchestration summaries in compact format. 1. Restate what you're changing
2. Name one assumption
## Skills Reference (All 24) 3. Check if it could break anything
### Core Orchestration
- **archeflow:run** -- Automated PDCA execution loop with `--start-from` and `--dry-run`
- **archeflow:orchestration** -- Step-by-step manual execution guide
- **archeflow:plan-phase** -- Explorer and Creator output formats and protocols
- **archeflow:do-phase** -- Maker implementation rules and worktree commit strategy
- **archeflow:check-phase** -- Shared reviewer protocols and output format
- **archeflow:act-phase** -- Post-Check decision logic: collect findings, route fixes, exit or cycle
### Quality and Safety
- **archeflow:shadow-detection** -- Quantitative dysfunction detection and correction
- **archeflow:attention-filters** -- Context optimization per archetype
- **archeflow:convergence** -- Detects convergence, stalling, and oscillation in multi-cycle runs
- **archeflow:artifact-routing** -- Inter-phase artifact protocol for naming, storage, and routing
### Process Intelligence
- **archeflow:process-log** -- Event-sourced JSONL logging with DAG parent relationships
- **archeflow:memory** -- Cross-run learning from recurring findings
- **archeflow:effectiveness** -- Archetype scoring on signal-to-noise, fix rate, cost efficiency
- **archeflow:progress** -- Live progress file watchable from a second terminal
### Integration
- **archeflow:colette-bridge** -- Bridges ArcheFlow with the Colette writing platform
- **archeflow:git-integration** -- Git-per-phase commits, branch-per-run, rollback
- **archeflow:multi-project** -- Cross-repo orchestration with dependency DAG and shared budget
### Configuration
- **archeflow:custom-archetypes** -- Create domain-specific roles
- **archeflow:workflow-design** -- Design custom workflows with per-phase archetype assignment
- **archeflow:domains** -- Domain adapters for writing, research, and non-code workflows
- **archeflow:cost-tracking** -- Budget enforcement and model tier recommendations
- **archeflow:templates** -- Template gallery for sharing workflows, teams, and setup bundles
- **archeflow:autonomous-mode** -- Unattended overnight sessions
### Meta
- **archeflow:using-archeflow** -- This skill: session-start activation and quick reference