c/claude-archeflow-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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:
Christian Nennemann
2026-04-06 20:43:23 +02:00
parent 1baaa79946
commit 55de51aabe
2 changed files with 98 additions and 365 deletions
Download Patch File Download Diff File Expand all files Collapse all files

272
skills/sprint/SKILL.md
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
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
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
```
@@ -46,21 +40,12 @@ af-sprint --project writing.colette # Only process items for this project
### Step 0: Orient
```bash
# Load queue and workspace state
QUEUE=$(cat docs/orchestra/queue.json)
MODE=$(echo "$QUEUE" | jq -r '.mode')
```
Load queue from `docs/orchestra/queue.json`. Check mode (`AUTONOM` / `ATTENDED` / `PAUSED`).
Show one-line status: `sprint: AUTONOM | 7 pending (1xP0, 1xP2, 5xP3) | 4 slots`
Check mode:
- `AUTONOM` → proceed without asking
- `ATTENDED` → show plan, wait for user approval before each batch
- `PAUSED` → report status only, do not start tasks
Show one-line status:
```
sprint: AUTONOM · 7 pending (1×P0, 1×P2, 5×P3) · 4 slots
```
- `AUTONOM` -- proceed without asking
- `ATTENDED` -- show plan, wait for user approval before each batch
- `PAUSED` -- report status only, do not start tasks
### 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.
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.
4. **Cost-aware concurrency**:
- 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
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.
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
For each task in the batch, decide the execution strategy:
| Signal | Strategy | What happens |
|--------|----------|-------------|
| Estimate S, clear scope | **Direct** | Spawn Agent() with task description, no orchestration |
| Estimate M, multi-file | **Direct+** | Spawn Agent() with task + "read code first, run tests after" |
| Estimate L/XL, code | **Feature-dev style** | Agent explores → implements → self-reviews (see below) |
| Estimate L/XL, writing | **PDCA** | Use af-run with writing domain archetypes |
| Task contains "validate", "test", "lint", "check" | **Direct** | Cheap analytical task, no orchestration |
| Task contains "review", "audit", "security" | **Review** | Spawn Guardian + relevant reviewers only |
| Signal | Strategy |
|--------|----------|
| Estimate S, clear scope | **Direct** -- Agent with task description, no orchestration |
| Estimate M, multi-file | **Direct+** -- Agent with "read code first, run tests after" |
| 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 |
| validate/test/lint/check tasks | **Direct** -- cheap analytical, no orchestration |
| 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(prompt: "You are working on <project> at <path>. Task: <description>
1. EXPLORE: Read CLAUDE.md, docs/status.md, relevant source files.
2. PLAN: Identify files to change, write brief plan (what, where, why).
3. IMPLEMENT: Follow existing code patterns strictly.
4. TEST: Run project test suite, fix failures.
5. SELF-REVIEW: Re-read diff -- error handling, protocol compliance, test coverage.
6. COMMIT + PUSH: Conventional commits, signed, pushed.
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED")
```
### Agent Spawn Template
Spawn ALL batch agents in a **single message** (parallel execution). Each agent gets:
```
Agent(
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, and the relevant source files.
Understand existing patterns before writing anything.
2. PLAN: Identify 2-3 files to change. Write a brief plan (what, where, why).
If ambiguous, list your assumptions.
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.
<standard rules>
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED"
)
```
This gives the agent feature-dev's structured exploration without the multi-agent overhead.
For writing/research L/XL tasks, use af-run instead — archetypes add value where linters don't exist.
**Agent spawn template:**
For each task in the batch, spawn an Agent in the SAME message (parallel dispatch):
```
Agent(
description: "<project>: <task-short>",
prompt: "You are working on project <project> at <path>.
Task: <task description>
<notes if any>
prompt: "You are working on <project> at <path>. Task: <description>
Rules:
- Read the project's CLAUDE.md first
- Commit with: git -c user.signingkey=/home/c/.ssh/id_ed25519_dev.pub commit
- NO Co-Authored-By trailers
- Conventional commits
- Push when done: GIT_SSH_COMMAND='ssh -i /home/c/.ssh/id_ed25519_dev -o IdentitiesOnly=yes' git push origin main
- Commit: git -c user.signingkey=/home/c/.ssh/id_ed25519_dev.pub commit
- NO Co-Authored-By trailers, conventional commits
- Push: 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
- Report: what you did, what changed, any blockers
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED",
subagent_type: "general-purpose",
isolation: "worktree" # Only for L/XL tasks; S/M tasks run directly
isolation: "worktree" # Only for L/XL tasks; S/M run directly
)
```
**CRITICAL: Spawn all batch agents in a SINGLE message.** This enables parallel execution.
Do not spawn them sequentially.
### Step 3: Mark Running
After spawning, update the queue:
Update the queue after spawning:
```bash
# For each spawned task
./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
./scripts/ws start <task-id> # or update queue.json status to "running" directly
```
### 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|...`)
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>"
```
Update: `./scripts/ws done <task-id> -r "<summary>"` or `./scripts/ws fail <task-id> -r "<reason>"`
### 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 ──────────────────────────────
✓ writing.colette fanout run done (45s)
✓ book.3sets validation done (30s)
△ book.sos meta-book concept needs_context (missing outline)
✓ tool.archeflow af-review mode done (60s)
-- Sprint Batch 1 --------------------------------------------------
+ writing.colette fanout run done (45s)
+ book.3sets validation done (30s)
! book.sos meta-book concept needs_context
+ tool.archeflow af-review mode done (60s)
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
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
2. Run `./scripts/ws log --summary "<sprint summary>"` if available
3. Show final sprint report:
```
── Sprint Complete ─────────────────────────────
Duration: 12 min
Tasks: 5 completed, 1 blocked, 1 remaining (P3)
Projects touched: 4
Commits: 7
────────────────────────────────────────────────
```
2. Run `./scripts/ws log --summary "<sprint summary>"`
3. Show final report with duration, tasks completed/blocked/remaining, projects touched, commits
---
## Mode Behavior
### AUTONOM
- Dispatch immediately, no user confirmation
- Commit + push after each agent completes
- Only pause for BLOCKED tasks or budget exhaustion
- Report between batches (one-line status)
### 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 |
---
| Mode | Dispatch | Between batches | Stops for |
|------|----------|----------------|-----------|
| **AUTONOM** | Immediate | One-line status, no pause | BLOCKED or budget exhaustion |
| **ATTENDED** | Show batch, wait for approval | Show results, ask "Continue? [y/n/edit]" | User decision |
| **PAUSED** | No dispatch | -- | Always (status display only) |
## Error Recovery
- **Agent crashes mid-task**: Mark task as `failed`, add error to notes, continue with next batch
- **Git push fails**: Log the error, do NOT retry. User will handle push conflicts manually.
- **Queue file corrupted**: Run `./scripts/ws validate`. If invalid, stop sprint and report.
- **Budget exceeded**: Stop sprint, report remaining tasks and estimated cost.
- **All tasks blocked**: Report dependency graph, suggest which blockers to resolve first.
- **Agent crash**: Mark `failed`, continue with next batch
- **Git push fails**: Log error, do NOT retry -- user handles conflicts
- **Queue corrupted**: Run `./scripts/ws validate`, stop if invalid
- **Budget exceeded**: Stop sprint, report remaining tasks and estimated cost
- **All blocked**: Report dependency graph, suggest which blockers to resolve first

191
skills/using-archeflow/SKILL.md
View File

@@ -5,180 +5,51 @@ description: Use at session start when implementing features, reviewing code, de
# ArcheFlow -- Active
Multi-agent orchestration using archetypal roles and PDCA quality cycles.
## Session Start
On activation, print ONE line:
On activation, print ONE line then proceed silently:
```
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
### Use `/af-sprint` (primary mode) when:
- User says "run the sprint", "work the queue", "go autonomous"
- Multiple tasks are pending across projects
- The workspace queue (docs/orchestra/queue.json) has pending items
### 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 |
| Need | Command | When |
|------|---------|------|
| **Work the queue** | `/af-sprint` | Multiple tasks pending across projects, "run the sprint" |
| **Deep orchestration** | `/af-run` | Writing/research tasks, security-sensitive code, complex multi-module refactors |
| **Code review** | `/af-review` | Review diff/branch/commits before merging, security-sensitive changes |
| **Single feature** | `feature-dev` or direct | Clear scope, one project -- no orchestration needed |
## 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
- Answering questions (no code changes)
- Reading/exploring code without making changes
- Config changes to a single file
- Git operations (commit, push, branch)
## Workflow Selection
**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.
## Archetypes
| Archetype | Avatar | Virtue | Shadow | Phase |
|-----------|--------|--------|--------|-------|
| **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)
| Signal | Workflow | Pipeline |
|--------|----------|----------|
| Small fix, low risk | `fast` | Creator --> Maker --> Guardian |
| Feature, multi-file, moderate risk | `standard` | Explorer + Creator --> Maker --> Guardian + Skeptic + Sage |
| Security, breaking changes, public API | `thorough` | Explorer + Creator --> Maker --> All 4 reviewers |
## Available Commands
| Command | What it does |
|---------|-------------|
| `archeflow:run` | Automated PDCA loop -- single command to orchestrate a full run |
| `archeflow:orchestration` | Load manual PDCA execution guide |
| `archeflow:shadow-detection` | Load shadow monitoring rules |
| `archeflow:autonomous-mode` | Load autonomous/overnight session protocol |
| `archeflow:status` | Show current orchestration state (phase, cycle, active agents) |
| `archeflow:history` | Show past orchestration summaries from `.archeflow/session-log.md` |
| `/af-sprint` | Queue-driven parallel agent runner (primary mode) |
| `/af-run <task>` | PDCA orchestration loop (`--dry-run`, `--start-from`, `--workflow`) |
| `/af-review` | Guardian-led code review on diff/branch/range |
| `/af-status` | Current run state, active agents, findings |
| `/af-report` | Full process report for a run |
| `/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`
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
## Mini-Reflect Fallback
### `archeflow:history`
Read `.archeflow/session-log.md` and show the last 5 orchestration summaries in compact format.
## Skills Reference (All 24)
### 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
Even when skipping ArcheFlow, apply for non-trivial changes:
1. Restate what you're changing
2. Name one assumption
3. Check if it could break anything