work

# Work: FSM Lifecycle Router (v3) **One entry point for all work.** Concurrent FSM with PLANNING and EXECUTION phases. Guard scoring runs constantly (not as a gate). DISCOVER runs interview, memory prefetch, prior art, and search concurrently. All artifacts stored as beads custom types. ``` PLANNING PHASE EXECUTION PHASE ┌───────────────────┐ ┌───────┐ ┌──────────┐ ┌─────────┐ ┌──────┐ ┌─────────┐ ┌──────────┐ ┌──────┐ ┌───────┐ │ DISCOVER │──▶│ ALIGN │──▶│ RESEARCH │──▶│ PROPOSE │──▶│ SPEC │──▶│ EXECUTE │──▶│ VALIDATE │──▶│ EMIT │──▶│ LEARN │ │ (concurrent) │ └───────┘ └──────────┘ └─────────┘ └──────┘ └─────────┘ └──────────┘ └──────┘ └───────┘ │ │ north star deeper code CDO graph BDD + spawn layer-dep close cm outcome │ ┌──────────────┐ │ ALIGN gate analysis 5-role contracts team/agents strictness bead cm reflect │ │ Interview(fg)│ │ classify C1-C4 map think accept. inline gates update br learning │ │ PriorArt(bg) │ │ layers DoR compl. proposal criteria cm add status cass index │ │ Search (bg) │ │ alignment bead (learn) │ └──────────────┘ │ verdict │ │ │ ╔════════════════╗│ Guard is NOT a step -- it scores 6 categories every turn. │ ║ GUARD(constant)║│ <=30% -> PASS | 30-60% -> ASK inline | >60% -> interview skill │ ╚════════════════╝│ └───────────────────┘ ``` --- ## Task Tracker Adapter (bd | br | td) The work skill is backend-agnostic for task tracking. Detect which tool is available and route through the adapter. **Preference order: bd > br > td.** ### Detection ```bash # Prefer bd (Go, auto-commit) > br (Rust, non-invasive) > td (Python, lightweight) command -v bd && TRACKER=bd || { command -v br && TRACKER=br || { command -v td && TRACKER=td || TRACKER=none; }; } ``` ### Operation Map | Operation | bd (preferred) | br (supported) | td (lightweight) | |-----------|---------------|-------------|------------------| | **create** | `bd create --title="..." --type=task` | `br create --title="..." --type=task` | `td add "..."` | | **list** | `bd list --status=open` | `br list --status=open` | `td` / `td -g {group}` | | **search** | `bd search "{kw}"` | `br search "{kw}"` | N/A (grep local) | | **show** | `bd show {id}` | `br show {id}` | `td {id}` | | **update** | `bd update {id} --status=X` | `br update {id} --status=X` | `td {id} edit` | | **close** | `bd close {id}` | `br close {id}` | `td {id} complete` | | **deps** | `bd dep add {p} {c}` | `br dep add {p} {c}` | N/A | | **ready** | `bd ready` | `br ready` | N/A | | **sync** | `bd sync` (auto-git) | `br sync --flush-only` + manual git | N/A (local SQLite) | | **epic** | `bd epic {id}` | `br epic {id}` | N/A (use groups: `td -g {epic}`) | ### Behavioral Differences - **bd sync** auto-commits and pushes — no manual git needed - **br sync** exports JSONL only — you must `git add .beads/ && git commit` manually - **td** has no sync/deps/ready — degrade gracefully (skip dep gates, no ready filtering) ### Degradation Rules When `td` is the only backend: - Skip dependency-based gates (no `dep` support) - Skip `ready` filtering (list all open instead) - Map groups to epics (`td -g {epic-name}`) - Search falls back to `td` + grep When no tracker is available (`TRACKER=none`): - Continue without task integration; note in artifact - Prior art check skips BD/tracker queries --- ## Responsibility Boundary - `lev` owns CLI/protocol routing only. - `work` owns lifecycle-stage logic and artifact contracts. - `lev-builder` owns build/migrate execution patterns. Do not place artifact-format instructions in command shims. Keep format contracts in this skill and its templates. --- ## Entity Lifecycle (7 States + Discarded Branch) ``` ephemeral → captured → classified → crystallizing → crystallized → manifesting → completed ↓ ↓ ↓ ↓ ↓ ↓ ↓ [none] [report [report + [proposal [spec [handoff [archive bead] alignment] bead] bead] bead] bead] ↘ discarded ``` | Stage | Bead Type | Sub-Skills | Keywords | |-------|-----------|-----------|----------| | **ephemeral** | None (brainstorm) | Inline | "explore", "brainstorm", "understand" | | **captured** | `custom:report` | `lev get`, `lev-research` | "get", "research", "analyze", "scan", "find", "lookup", "read", "ls" | | **classified** | `custom:report` + alignment | `work` ALIGN gate, `lev-portable` | "classify", "align", "categorize" | | **crystallizing** | `custom:proposal` | `lev-cdo`, `lev-learn`, `thinking-parliament` | "design", "propose", "architect", "learn", "guide me" | | **crystallized** | `custom:spec` | `planning`, tracker | "plan", "implement", "specify" | | **manifesting** | handoff bead | Team coordination, tracker | "working on", "in progress" | | **completed** | archive bead | `lev-lifecycle` | "done", "finished", "closed" | | **discarded** | tombstone link | `work` guard + validation | "discard", "drop", "reject" | Learning artifacts are created post-completion by LEARN, but `custom:learning` is not a lifecycle state. All artifacts are stored as beads custom types (not files on disk). A hook generates markdown views from beads for human readability. --- ## Shortcuts | Key | Action | Route | |-----|--------|-------| | `(l)` | Start learn interview | `learn [context]` | | `(p)` | Start proposal | `work --stage=crystallizing` | | `(u)` | Show update diff | `work --stage=update` | | `(s)` | Browse skills | skills-db query (inline) | | `(d)` | Design/UX hub | `ux` hub | --- ## Operational Command Constellation These are agent <-> human operational commands and aliases. Map them to root primitives, not ad-hoc flows. Canonical source for CLI alias + FSM stage + schema handler mapping: - `~/.agents/skills/work/references/command-matrix.md` | Command / Alias | Primitive | Route | Notes | |-----------------|-----------|-------|-------| | `work` | lifecycle | `work` | DISCOVER -> ALIGN -> route | | `plan` | crystallized-intent | `work` -> SPEC | Legacy alias normalized to spec output | | `spec` | crystallized | `work` -> SPEC | Primary crystallized artifact | | `propose` | proposal | `work` -> PROPOSE | CDO graph deliberation | | `tracker` | execution tracking | tracker (br/bd/td) | Task graph + status | | `check` | validation | `work` VALIDATE | Alignment, DoR, drift | | `go` | execute | `work` -> EXECUTE | Start manifesting | | `handoff` | continuity | `work` EMIT | Canonical checkpoint output | | `exit` | session close | `work` EMIT -> LEARN | Emit handoff + learn ceremony | | `learn` | guided intake | `lev-learn` via DISCOVER | Interview loop (foreground track) | | `align` | alignment | `work` -> ALIGN gate | North star check, drift detection | | `workflow` | workflow mgmt | `workflow` | List/create/run workflow skills | | `skill` | skill ops | `skill-builder` or skill lookup | Build/discover/install path | | `ask`, `wiz` | wizard mode | `interview` via DISCOVER | Guard >60% routes here automatically | | `scan`, `security` | assurance | `work` VALIDATE | Can route to specialist security skills | | `daemon`, `daemons` | runtime ops | `lev-core` | Operational status/health | | `reflect` | learning | `work` LEARN | cm reflect + learnings bead | ### External Context Primitive Use `lev get` as the root external context-gathering primitive. Compatibility note: if `lev get` is not available in the current CLI build, use `lev find` as a temporary alias. Aliases that resolve here: - `ls`, `read`, `search`, `find`, `lookup`, `scan`, `research`, `prior art` Progressive depth: - `context` -> current conversation/workspace state - `fs` -> filesystem and local artifacts - `tracker` -> task graph and open work (br/bd/td) - `beads` -> bead search (br search, cass search) - `research` -> external sources --- ## Quick-Keyword Artifact/Action Glossary | Keyword(s) | Stage | Bead Type | Action | |------------|-------|-----------|--------| | "get", "research", "analyze", "scan", "find", "lookup", "read", "ls" | captured | `custom:report` | DISCOVER -> `lev get` (or `lev-research` for deep mode) | | "align", "north star", "drift", "classify" | classified | `custom:report` | ALIGN gate (embedded) | | "design", "propose", "architect" | crystallizing | `custom:proposal` | PROPOSE -> `lev-cdo` + 5-role Think | | "learn", "guide me", "unstuck" | crystallizing | `custom:proposal` | DISCOVER interview track -> PROPOSE | | "plan", "implement", "specify" | crystallized | `custom:spec` | SPEC -> `planning` + tracker | | "working on", "in progress", "handoff", "exit" | manifesting | handoff bead | EXECUTE -> EMIT | | "done", "finished", "closed" | completed | archive bead | EMIT -> LEARN -> `lev-lifecycle` | | "reflect", "learnings", "retro" | completed (post-close) | `custom:learning` | LEARN -> `cm reflect` + `br create` | --- ## FSM States: PLANNING PHASE ### DISCOVER -- Concurrent Context Gathering DISCOVER is the entry point. It runs four tracks concurrently with a constant guard scoring function. All results save to `custom:report` beads. ``` /work "{idea}" │ ▼ DISCOVER (concurrent, not sequential) ├── Interview (foreground) │ └── Ask user questions, rolling bg research per question ├── Memory Prefetch (background) │ └── cm context + cass search (workspace-first, global fallback) ├── Prior Art (background) │ └── br search, lev get, cass search, tracker list ├── Search (background) │ └── Codebase grep, online search, skill discovery └── Guard (constant -- runs every turn, not a pre-step) ├── Score 6 categories: Objective, Scope, Constraints, Environment, │ Dependencies, Success Criteria ├── Each scored: MISSING (full weight) | PARTIAL (half) | PRESENT (0) ├── Weights: Objective (20%), Scope (20%), Constraints (15%), │ Environment (15%), Dependencies (15%), Success Criteria (15%) │ ├── Score <=30% -> PASS (sufficient, advance to ALIGN) ├── Score 30-60% -> ASK (structured questions inline) └── Score >60% -> route to interview skill (wizard-mode) ``` **Confidence formula:** ``` base_confidence = 1.0 - (guard_score / 100) layer_modifier: Site/Structure -0.1, Skin/Services +0.0, Space +0.05, Stuff +0.1 think_modifier: agreement >80% +0.1, 50-80% +0.0, <50% -0.1 final = base + layer_modifier + think_modifier ``` **Memory prefetch** runs as part of DISCOVER before heavy research fan-out: | Step | Command | Policy | |------|---------|--------| | Procedural recall | `cm context "{kw}" --workspace "$PWD" --limit 3 --history 1 --json` | Workspace-first |