Date: 2026-02-28 GitHub Issue: specledger/specledger#43 Status: In Progress
Decision: Adopt a 4-layer tooling model
| Layer | Name | Runtime | Purpose |
|---|---|---|---|
| 0 | Hooks | Invisible, event-driven | Auto-capture sessions on commit |
| 1 | sl CLI |
Go binary, no AI needed | Data operations, CRUD, standalone tooling |
| 2 | Slash commands | Claude Code prompts | AI workflow orchestration (specify→implement) |
| 3 | Skills | Passive context injection | Domain knowledge for agent decision-making |
Cross-layer interactions: Layers are not strictly isolated — the CLI (L1) can reach into other layers:
- L1→L0:
sl auth hook --installconfigures hooks - L1→L2:
sl revisegenerates a prompt and spawnsclaude --prompt(launcher pattern) - L2→L1: Slash commands call CLI tools (e.g.,
/specledger.taskscallssl issue create)
These cross-layer interactions are convenience patterns, not additional layers.
Note on Skills (Layer 3): Skills are installed per-repo based on tech stack. A future sl skill subcommand could discover and install skills (similar to vercel-labs/skills find.ts). This is a separate proposal from command consolidation. This should be considered part of repo bootstrap and template management.
Decision: CLI = data operations, Slash command = AI reasoning
| Responsibility | Layer | Example |
|---|---|---|
| CRUD on entities (issues, comments, deps) | CLI (L1) | sl comment reply, sl issue close |
| Fetching/displaying data | CLI (L1) | sl revise --summary, sl issue list |
| Analyzing, reasoning, deciding | Slash command (L2) | /specledger.clarify analyzes gaps |
| Applying changes based on reasoning | Slash command (L2) | Agent edits files, then calls sl comment resolve |
The revise middle ground: sl revise (CLI) remains as an optional launcher that pre-filters comments and spawns an agent. The agent's behavior is defined by the slash command (/specledger.clarify --comments), and the agent uses sl comment reply/resolve for granular, detailed resolution. This eliminates the current tension where:
- The CLI tried to interpret agent results post-session (clunky)
- Comments were bulk-resolved without detail
Key principle: The agent should have proper CLI tools to perform data operations with full context, rather than the CLI guessing what the agent accomplished. When control flow resumes in the CLI, it should warn and prompt the user to let the agent do commits/resolve comments directly for better traceability and remove logic to resolve comments or do git operations from the CLI (except from the beginning where the CLI does help make sure the right branch is checked out and any changes are taken care (stash or allow user to cancel and commit first before relaunching revise)).
Side note: The /specledger.revise slash command was removed from playbook templates after the sl revise CLI command was merged, but existing repos that were bootstrapped before the removal still have the stale command. Template management should:
- Own the
specledger.prefix in.claude/commands/ - On
sl doctor --templateorsl init, detect and prompt to remove commands that are no longer in the playbook - Never silently delete user-modified commands — prompt first
Status: Open — needs separate proposal for template lifecycle management.
Decision: Consolidate slash commands while preserving SpecKit nomenclature
| Command | Absorbs | Stage |
|---|---|---|
/specledger.specify |
— | Core pipeline |
/specledger.clarify |
/specledger.revise |
Core pipeline (agent uses sl comment for granular resolution) |
/specledger.plan |
— | Core pipeline |
/specledger.tasks |
— | Core pipeline |
/specledger.implement |
/specledger.resume |
Core pipeline |
/specledger.analyze |
— | Quality validation (keeps SpecKit brand name) |
/specledger.checklist |
— | Optional quality gate (standalone, per-feature custom gates) |
/specledger.onboard |
/specledger.help |
Setup |
/specledger.constitution |
— | Setup (runs rarely) |
/specledger.audit |
— | Codebase analysis |
| Removed | Reason |
|---|---|
/specledger.resume |
Duplicate of /specledger.implement |
/specledger.revise |
Absorbed by /specledger.clarify + sl comment CLI |
/specledger.help |
Absorbed by /specledger.onboard welcome step |
/specledger.adopt |
Moves to CLI as sl spec link (branch→spec mapping is deterministic, not AI) |
/specledger.add-deps |
Agent calls sl deps add directly |
/specledger.remove-deps |
Agent calls sl deps remove directly |
sl comment list/show/reply/resolve/pull/push — enables agents to manage review comments with full detail rather than bulk resolution.
Decision: Keep skills separate, lean, and progressively loaded
- Skills are silently injected into agent context as needed
- Each CLI domain gets its own skill (
sl-issue-tracking,specledger-deps, futuresl-comment) - Skills must be focused and isolated — not consolidated into a monolith
- Slash commands reference CLI tools briefly (triggering skill loading), skills provide the deep usage patterns
- Skill discovery/install is a separate concern (future
sl skillcommand, part of bootstrap/template management)
Pattern: sl comment follows the same pattern as sl issue:
- No dedicated slash command mapping
- A
sl-commentskill teaches the agent when/how to usesl comment /specledger.clarifyreferences comments briefly, which triggers the skill to load progressively
sl graph is currently stubbed ("coming soon") with show, export, transitive subcommands. Meanwhile sl issue list --graph already shows task dependency graphs. The sl graph command should be scoped to spec dependency visualization and folded into sl deps (e.g., sl deps graph), not kept as a top-level command.
Currently only sl playbook list. Future: playbook management at org level via the SpecLedger web app. Note for proposal.
Beads migration tooling stays as a safety net. Even with beads removed from this repo, other projects may still need it.
Decision: sl init should offer to launch the onboarding workflow after filesystem setup
Flow:
sl initcreates.claude/,specledger/,specledger.yaml(existing behavior)- New: Prompt user: "Launch guided onboarding? (Y/n)"
- Default (Y):
sl initspawnsclaude --prompt "/specledger.onboard"(launcher pattern, same assl revise) - Opt-out (n): Print instructions showing how to call
/specledger.onboardmanually (advanced users)
- Default (Y):
This mirrors the sl revise launcher pattern (D2) and gives new users a seamless path from sl init to their first feature spec.
| CLI Command | Purpose | Notes |
|---|---|---|
sl auth |
Authentication management | L1→L0 cross-layer (hook --install) |
sl doctor |
Environment health check | Auto-updates CLI + templates |
sl version |
Version info | — |
sl playbook |
List/manage playbooks | Future: org-level management in web app (T3) |
sl deps |
Dependency management | Absorbs sl graph (D6) |
sl session |
AI session capture | Invisible via hooks (L0); list/get for audit |
sl new |
Project creation (TUI) | — |
sl issue |
Issue CRUD | Skill-driven agent usage |
sl comment (new) |
Comment CRUD | Skill-driven agent usage |
sl spec link (new) |
Branch→spec mapping | Replaces /specledger.adopt (D9) |
| CLI Command | Launches | Agent Behavior Defined By |
|---|---|---|
sl revise |
claude --prompt with comment context |
/specledger.clarify + sl-comment skill |
sl init (proposed D7) |
claude --prompt "/specledger.onboard" |
/specledger.onboard |
| Command | Stage | CLI Tools Called |
|---|---|---|
/specledger.specify |
Core pipeline | sl issue create (optional) |
/specledger.clarify |
Core pipeline | sl comment list/reply/resolve |
/specledger.plan |
Core pipeline | — |
/specledger.tasks |
Core pipeline | sl issue create/link |
/specledger.implement |
Core pipeline | sl issue update/close |
/specledger.analyze |
Quality validation | sl comment list --status open (flag unresolved) |
/specledger.checklist |
Optional quality gate | — |
/specledger.onboard |
Setup | Orchestrates other slash commands |
/specledger.constitution |
Setup | — |
/specledger.audit |
Codebase analysis | — |
Decision: Move adopt functionality from slash command to CLI
The original purpose of /specledger.adopt was branch-name reconciliation — mapping non-conforming branch names (created by other tools) to the strict naming convention used by the deterministic create-new-feature.sh script. This is a deterministic data operation, not AI reasoning.
New CLI command: sl spec link <branch-name> <spec-slug> — creates a mapping entry so the spec artifact directory resolves correctly regardless of branch naming.
Decision: Replace .specledger/scripts/bash/ scripts with sl CLI subcommands
Several slash commands (notably /specledger.specify) call bash scripts like create-new-feature.sh for deterministic operations. These scripts:
- Don't work on Windows (sometimes have PowerShell equivalents, sometimes not)
- Are a maintenance burden (two codepaths for the same operation)
- Should be replaced by cross-platform
slCLI commands
Migration path: Each bash script's functionality should be identified and absorbed into the appropriate sl subcommand. The CLI (Go binary) is already cross-platform.
Status: Needs inventory of all scripts and their CLI equivalents.
Decision: The core workflow (specify→clarify→plan→tasks→implement) is immutable. Playbooks customize content, not workflow shape.
| Concept | Owns | Does NOT own |
|---|---|---|
| Core workflow | Pipeline stages (specify→implement) | — |
| Playbooks | Suggested skills, templates, constitution defaults | Workflow stage order or additions |
| Skills | Domain-specific patterns injected per-stage | Pipeline structure |
Rationale: The specify→plan→tasks→implement workflow has been tested across different teams (data, ML, platform) and works universally. Playbooks are a fast way to propose known skills and templates for a given tech stack or team type, allowing orgs to fine-tune without breaking the core workflow.
Future: Org-level playbook management in the SpecLedger web app.
Decision: /specledger.checklist remains as a standalone optional command, not merged into /specledger.analyze
Rationale: Checklist was a late addition from SpecKit that never fully landed. Its purpose (custom per-feature quality gates on top of the constitution) is distinct from analyze (cross-artifact consistency). Keeping it optional lets teams that want custom gates use it without cluttering the core pipeline.
Note: May evolve to become a constitution-level feature in the future. Defer deeper design.
Tension: During the implement phase, there is no structured mechanism to track where the agent and human diverged from the plan. Session capture (L0) records the conversation, but doesn't produce a readable "deviation log" that maps plan→actual.
Impact: Reviewers of the final implementation can't easily tell what changed from the original plan without reading full session transcripts.
Potential solutions:
- A hook (L0) that logs structured entries on task completion (what was planned vs what was done)
/specledger.implementmaintaining adeviations.mdorchangelog.mdalongside tasks.mdsl sessionenrichment: tag session segments with the task ID being worked on, so you can query "show me what happened for task SL-abc123"
Status: Open — needs design spike.
Tension: sl revise and sl init (proposed) both use the launcher pattern (CLI spawns claude --prompt). Should this generalize to sl specify, sl plan, sl implement?
Trade-offs:
- Pro: Consistent UX — developers always start with
sl <verb> - Pro: CLI can do pre-flight checks (branch, auth, stash) before launching
- Con: Adds indirection — user could just type
/specledger.specifydirectly - Con: Each launcher needs to know what context to pre-fetch
- Con: Not enough usage data to know if this helps or hinders
Status: Deferred — need real user feedback on sl revise and sl init patterns first.
Tension: If playbooks only bundle skills, what distinguishes a playbook from a package.json-like dependency list? Is there room for playbooks to own more (e.g., default constitution values, org-specific templates, CI/CD integration)?
Status: Deferred — depends on org-level playbook management design.
| # | Question | Status |
|---|---|---|
| Q1 | Should the CLI launcher pattern generalize beyond sl revise and sl init? |
Tension T2 — deferred |
| Q2 | How should sl doctor --template handle stale commands from older playbook versions? |
D3 — needs template lifecycle proposal |
| Q3 | Should sl skill discover/install skills based on repo tech stack? |
Deferred — separate proposal |
| Q4 | Inventory of bash scripts to replace with CLI commands? | D10 — needs script audit |
| Q5 | How to track plan→actual deviations during implementation? | Tension T1 — needs design spike |
| # | Question | Decision | Date |
|---|---|---|---|
| D1 | Layer model | 4-layer (Hooks → CLI → Commands → Skills) with cross-layer interactions | 2026-02-28 |
| D2 | CLI vs slash command responsibility | CLI = data ops, Command = AI reasoning, Launcher = optional convenience | 2026-02-28 |
| D3 | Template management | specledger. prefix is owned by playbook; stale commands should be detected and prompted for removal |
2026-02-28 |
| D4 | Slash command consolidation | 16 → 10 commands; analyze keeps SpecKit name; checklist stays standalone |
2026-02-28 |
| D5 | Skills architecture | Keep separate, lean, progressively loaded; no consolidation | 2026-02-28 |
| D6 | sl graph cleanup |
Fold into sl deps graph; sl issue list --graph handles task graphs |
2026-02-28 |
| D7 | sl init → onboard launcher |
Prompt user to launch onboarding after init (default yes, opt-out for advanced) | 2026-02-28 |
| D8 | Full CLI ↔ layer mapping | Complete mapping documented; no gaps remaining | 2026-02-28 |
| D9 | Adopt → CLI | Move to sl spec link (branch→spec deterministic mapping) |
2026-02-28 |
| D10 | Phase out bash scripts | Replace with cross-platform sl CLI subcommands |
2026-02-28 |
| D11 | Core workflow immutability | specify→plan→tasks→implement is fixed; playbooks = skill bundles | 2026-02-28 |
| D12 | Checklist fate | Keep as optional standalone; not merged into analyze | 2026-02-28 |