SHEAF

SHEAF is an opinionated, single-architect workflow system for planning and executing software work with strong continuity across sessions.

The name comes from sheaf theory in mathematics: local data that glues together coherently to form a global structure. The metaphor is intentional — Sheaf takes local pieces of context (tasks, decisions, code, architecture) and articulates them into a coherent AI-assisted flow.

It is designed for day-to-day implementation work with one core principle:

• always maintain momentum with exactly one clear next action.

---

See also

• QUICKSTART.md — compact daily operating guide

---

Installation

SHEAF is installed with a guided project installer:

npx viespejo/sheaf

Choose installation mode

• Interactive (Recommended): Simply run the command above and follow the prompts.
• Flags: Use specific flags to automate the installation.

Recommended commands

Install for CodeCompanion (Neovim):

npx viespejo/sheaf --codecompanion

Install for Claude Code:

npx viespejo/sheaf --claude

Install for Gemini CLI:

npx viespejo/sheaf --gemini

Preview without writing files:

npx viespejo/sheaf --codecompanion --dry-run

Custom installation (multiple runtimes, global paths, custom directory):

npx viespejo/sheaf --codecompanion --claude --gemini --scope global --install-dir ~/.ai

Installation Parameters

• Scope (-s, --scope):
  • local (default): References are rewritten relative to the agent's own directory (e.g., ./.codecompanion/).
  • global: References are rewritten as absolute paths to the installation target.
• Install Directory (-t, --install-dir): The base directory where agent folders will be created.
• Runtimes: Use any combination of --codecompanion, --claude, and --gemini to select which artifacts to install.

What gets installed

Each selected runtime receives its own directory (.codecompanion/, .claude/, or .gemini/) containing:

• prompts/sheaf/ (CodeCompanion) or commands/sheaf/ (Claude/Gemini)

• sheaf/templates/

• sheaf/workflows/

• sheaf/references/

• sheaf/skills/

• sheaf/rules/ (if present)

Path rewriting and Adaptation behavior

During install, markdown references using the {{SHEAF_RUNTIME_DIR}} placeholder are rewritten automatically based on the chosen Scope.

Runtime prompt behavior:

• CodeCompanion and Claude receive markdown prompt outputs.
• Gemini receives TOML command outputs generated from composed markdown prompts.

Important notes

• Installation is copy-based; existing files at the target can be overwritten.
• If no runtime flags are provided, the installer runs in interactive mode.

---

Context Priming for LLM Sessions (Optional)

If you want to avoid repetitive repository discovery (ls, find, cat) at the start of a coding session, you can generate a structured context snapshot manually before chatting with an LLM.

Reference path:

• {{SHEAF_RUNTIME_DIR}}/tools/context-dump.sh

Concrete installed path:

• Shared runtime assets: .sheaf-runtime/tools/context-dump.sh

Run the command from the project root you want to snapshot.

Usage patterns

Ephemeral output to stdout (default):

bash .sheaf-runtime/tools/context-dump.sh

Save output to file (optional):

bash .sheaf-runtime/tools/context-dump.sh --out context.md

Add ad-hoc files at runtime:

bash .sheaf-runtime/tools/context-dump.sh --include docs/decisions.md

.contextdump and --include

• .contextdump is optional.
• When present, it is read from the project root (one relative path per line, comments allowed).
• --include appends extra files at runtime.
• Entries from .contextdump and --include are merged with deduplication.

Optional direct execution

Canonical usage is bash <path>, but you can run it directly if executable:

chmod +x .sheaf-runtime/tools/context-dump.sh
./.sheaf-runtime/tools/context-dump.sh

• convert product/architecture intent into executable plans,
• execute plans with explicit control per task,
• reconcile results into durable summaries,
• preserve session continuity so you can resume quickly,
• avoid decision fatigue through deterministic routing.

SHEAF is intentionally not a generic framework with many setup branches. It is optimized for practical, personal software delivery.

---

Core philosophy

1) Document-first, state-first

• Initialization starts from your docs (docs/prd.md, docs/architecture.md).
• Ongoing work is guided primarily by .sheaf/STATE.md, .sheaf/ROADMAP.md, and .sheaf/PROJECT.md.
• Existing SHEAF artifacts are your operational memory.

2) One-next-action invariant

At the end of every command/workflow, SHEAF should route to one deterministic next step.

No action menus. No “pick 1 of 4” fatigue.

3) PLAN → APPLY → UNIFY loop discipline

Every unit of work follows the loop:

• PLAN: decide and approve work
• APPLY: execute tasks with explicit choices
• UNIFY: reconcile what actually happened

Skipping phases reduces traceability and quality.

4) Continuity by design

SHEAF treats continuity as first-class:

• STATE.md for ongoing digest,
• HANDOFF*.md for session transfer,
• resume and progress commands for deterministic routing.

---

SHEAF structure

After initialization, SHEAF uses this structure:

.sheaf/
  PROJECT.md
  ROADMAP.md
  STATE.md
  sheaf.json
  execution-log.json            # created/updated as needed by APPLY
  HANDOFF-*.md                 # created by handoff command
  handoffs/archive/            # used by resume lifecycle
  phases/
    NN-phase-name/
      NN-PP-PLAN.md
      NN-PP-SUMMARY.md

---

Commands overview

/sheaf:init

Initialize SHEAF from docs and create core .sheaf artifacts.

• Primary use: first setup in a repository.
• Required docs: docs/prd.md, docs/architecture.md.
• Auto-includes PLANNING.md if present.
• May run interview mode for critical ambiguity.
• Ends with one action: /sheaf:plan.

/sheaf:plan

Create or continue one implementation plan for a selected story.

• Collaborative-first: discuss in chat before writing files.
• Uses INIT artifacts as primary context.
• Writes PLAN only after explicit approval.
• Updates state/roadmap after approval.
• Ends with one action: /sheaf:apply [plan-path].

/sheaf:brainstorming

Run a BMAD-style interactive brainstorming session with continuity.

• Detects previous brainstorming sessions and supports continue/new selection.
• Supports 4 approach modes: user-selected, AI-recommended, random, progressive flow.
• Facilitates collaborative ideation before convergence.
• Organizes ideas into themes and produces prioritized action steps.
• Persists session notes in .sheaf/brainstorming/ for later continuation.
• Ends with one deterministic next action.

/sheaf:apply

Execute an approved plan with per-task user control.

For each task, SHEAF shows a preview and requires a decision:

1. manual apply (you edit and confirm),
2. SHEAF apply (agent writes changes),
3. skip (logged as deviation).

• Supports stop/pause behavior with continuity.
• Logs outcomes for reconciliation.
• Routes to /sheaf:unify [plan-path] when execution is complete.

/sheaf:unify

Reconcile planned vs actual execution and close the loop.

• Creates SUMMARY.md next to PLAN.
• Updates STATE.md loop position.
• Updates ROADMAP.md where applicable.
• Runs transition workflow if phase is fully unified.
• Ends with one action: /sheaf:plan.

/sheaf:resume

Restore context at the start of a new session.

• Reads .sheaf/STATE.md.
• Detects optional handoff (.sheaf/HANDOFF*.md or provided path).
• Reconciles handoff vs state (state-first if stale/conflicting).
• Suggests exactly one next action.
• Archives consumed handoff after user proceeds.

/sheaf:progress

Mid-session checkpoint with deterministic routing.

• Reads STATE.md + ROADMAP.md.
• Shows milestone/phase/loop status.
• Supports optional user context (time limit, blocker, priority).
• Suggests exactly one next action.
• Adds context advisory when deep/critical risk is detected.

/sheaf:handoff

Generate a comprehensive continuity document for the next session.

• Synthesizes state + session evidence + optional notes.
• Creates .sheaf/HANDOFF-{timestamp}-{context}.md.
• Includes accomplishments, decisions, gaps, open questions, references, and prioritized next actions.
• Updates STATE.md Session Continuity with handoff pointer.

/sheaf:product-brief

Create or update product briefs through guided or autonomous discovery using the BMAD Product Brief skill.

• Objective: Guides you from raw ideas to polished executive summaries (1-2 pages) and optionally an LLM distillate for PRD creation.
• Modes:
  • Guided (Default): Conversational discovery with soft gates.
  • Yolo: Fast-track drafting followed by refinement.
  • Autonomous: Headless execution for structured inputs or flags (--autonomous).
• Features:
  • Contextual Discovery: Analyzes local artifacts and performs web research via specialized subagents.
  • Multi-lens Review: Uses Skeptic and Opportunity reviewers to stress-test the draft.
  • Distillate Generation: Captures technical details, rejected ideas, and requirements for downstream use.

/sheaf:create-prd

Create a new Product Requirements Document (PRD) from scratch using the BMAD Create PRD skill.

• Objective: Transform a product brief or raw requirements into a structured, comprehensive PRD.
• Process: Follows a specialized workflow to ensure all critical sections (context, goals, user stories, technical requirements, etc.) are addressed.

/sheaf:edit-prd

Edit and refine an existing PRD using the BMAD Edit PRD skill.

• Objective: Update, expand, or pivot an existing requirements document based on new feedback or changing scope.
• Process: Maintains document consistency while incorporating specific changes.

/sheaf:validate-prd

Validate a PRD against organizational or quality standards using the BMAD Validate PRD skill.

• Objective: Ensure a PRD is complete, consistent, and ready for implementation.
• Process: Analyzes the document for gaps, ambiguities, and alignment with project goals.

---

Maintenance Tools

bin/fix-skill-paths.js

Standardizes relative paths in skill prompts to absolute SHEAF-style paths. Use this when developing or updating skills to ensure all internal references (prompts, agents, resources, etc.) are correctly resolved during installation.

• Usage: node bin/fix-skill-paths.js <skill-name>
• Features:
  • Resolves folder references (prompts/, agents/, etc.) relative to the current file.
  • Resolves direct .md file references within the same directory.
  • Automatically handles ../ and ./ prefixes.
  • Verifies file existence for local references to avoid false positives.

---

Workflow files (engine behavior)

SHEAF command behavior is defined in these workflow documents:

• src/workflows/init-project.md
• src/workflows/plan-phase.md
• src/workflows/apply-phase.md
• src/workflows/unify-phase.md
• src/workflows/transition-phase.md
• src/workflows/resume-project.md
• src/workflows/progress-project.md
• src/workflows/handoff-project.md

Think of commands as entrypoints and workflows as operational contracts.

---

Reference files

Shared rules and guidance:

• src/references/loop-phases.md

  • loop semantics,
  • phase invariants,
  • transition conditions,
  • anti-patterns.

• src/references/plan-format.md

  • expected plan shape and conventions.

• src/references/context-management.md

  • context brackets (FRESH/MODERATE/DEEP/CRITICAL),
  • lean context loading,
  • handoff and continuity guidance.

---

Template files

SHEAF uses templates for consistent artifacts:

• src/templates/PROJECT.md
• src/templates/ROADMAP.md
• src/templates/STATE.md
• src/templates/PLAN.md
• src/templates/SUMMARY.md

---

Standard daily flow

A typical work cycle:

1. Start session: /sheaf:resume
2. Check orientation (optional): /sheaf:progress
3. Plan next unit: /sheaf:plan
4. Execute: /sheaf:apply [plan-path]
5. Reconcile/close: /sheaf:unify [plan-path]
6. End session safely: /sheaf:handoff

For quick mid-session checks, use /sheaf:progress at any point.

---

When to use resume vs progress vs handoff

• Use resume when starting a new session and you need context restoration.
• Use progress during an active session for a status checkpoint + next action.
• Use handoff before stopping work when continuity risk exists.

Quick rule:

• new session → resume
• same session, unsure next step → progress
• ending session / context risk → handoff

---

Loop routing logic (simplified)

Given loop markers in state:

• PLAN ○ → /sheaf:plan
• PLAN ✓, APPLY ○ → /sheaf:apply [plan-path]
• PLAN ✓, APPLY ✓, UNIFY ○ → /sheaf:unify [plan-path]
• PLAN ✓, APPLY ✓, UNIFY ✓ → /sheaf:plan (next work unit)
• blocked → address blocker first

Always one action.

---

APPLY task decision contract

During APPLY, each task must end in an explicit outcome:

• manual
• agent_applied
• skipped
• stopped

This contract is mandatory so UNIFY can reconcile accurately.

---

State hygiene guidelines

Keep .sheaf/STATE.md as a digest, not an archive.

Recommended practices:

• update after major state transitions,
• keep only active blockers/deferred issues,
• keep continuity section explicit and current,
• avoid bloating state with full historical detail,
• rely on SUMMARY.md + handoffs for deeper history.

---

Context management model

SHEAF tracks context pressure with practical brackets:

• FRESH (>70%): normal pace
• MODERATE (40–70%): reinforce core context
• DEEP (20–40%): reduce reads, prepare continuity
• CRITICAL (<20%): finish safely, write handoff

At DEEP/CRITICAL, avoid starting broad new work without continuity preparation.

---

Output quality expectations

Planning quality

• one story per plan,
• clear acceptance criteria,
• explicit boundaries,
• tasks with files/action/verify/done,
• explicit approval before execution.

Execution quality

• preview before writes,
• explicit per-task user decision,
• boundary respect,
• deviations logged.

Reconciliation quality

• SUMMARY reflects actual outcomes,
• criteria pass/fail/partial with evidence,
• deferred items explicit,
• state and roadmap synchronized.

---

Known invariants and anti-patterns

Invariants

• never execute without approved plan,
• never skip UNIFY after APPLY,
• never end workflow with ambiguous/multiple next actions,
• never invent execution results when evidence is missing.

Anti-patterns

• loading everything “just in case”,
• reflexive dependency chains in plans,
• silent scope drift beyond boundaries,
• postponing summary/state updates until “later”.

---

Practical command examples

/sheaf:init
/sheaf:plan
/sheaf:apply .sheaf/phases/04-workflows-layer/04-01-PLAN.md
/sheaf:unify .sheaf/phases/04-workflows-layer/04-01-PLAN.md
/sheaf:resume
/sheaf:resume .sheaf/HANDOFF-20260329-1845-phase04-apply.md
/sheaf:progress
/sheaf:progress only 30 minutes today
/sheaf:handoff
/sheaf:handoff pending db migration decision + test gap on auth module

---

Suggested operating routine

Start of day:

1. run /sheaf:resume,
2. accept or correct the suggested next action,
3. if needed run /sheaf:progress for extra orientation.

During work:

1. keep loop discipline,
2. use progress for checkpoints,
3. avoid starting new large scope at deep/critical context.

End of day:

1. run /sheaf:handoff,
2. verify top next action is explicit,
3. next session begins with /sheaf:resume.

---

Current command set in this repo

Available prompt entrypoints under src/prompts/:

• init.md
• plan.md
• apply.md
• unify.md
• resume.md
• progress.md
• handoff.md
• product-brief.md
• create-prd.md
• edit-prd.md
• validate-prd.md
• brainstorming.md

If your runtime requires explicit command registration outside prompt files, wire these entrypoints in your host configuration.

---

Final principle

SHEAF is most effective when you optimize for continuity, traceability, and momentum:

• plan clearly,
• execute intentionally,
• reconcile honestly,
• preserve context before it is lost,
• keep moving with one clear next step.