@spec-graph/core

spec-graph v3.1 engine — declaration engine + task lifecycle manager

A TypeScript library that provides the declaration engine behind spec-graph. Consumed by @spec-graph/cli and SKILL.md files. Brain, not hands — generates dispatch manifests, evaluates gates, and tracks task lifecycle. Never executes agents directly.

Modules

| Module | Responsibility | |--------|----------------| | automator | Session lifecycle, 9-stage FSM, task tracking (start/review/complete), story generation | | session-index | Global session CSV index, structured ID allocation (<abbrev>-<YYYYMMDD>-<NNN>), migration, reconcile | | planning | Intent → capability decomposition (LLM manifest + keyword fallback) | | gate-enforcement | Load gate.yaml, evaluate entry/exit criteria, produce diagnosis | | dispatch | Generate routing manifests with task lifecycle steps (pre_step/post_step/complete_step) | | composer | Scan packs and compose graph.yaml | | recovery | 4-level progressive retry strategy with Jaccard similarity detection | | sense | Project feature detection (language, framework, runtime) | | machine-state | Track artifact status per stage and capability | | meeting | MeetingManager lifecycle (create/record/advance/complete) | | isolation | WorktreeManager + ScopeLock + MergeQueue for parallel execution | | integration-gate | Three-level gate (individual → merge → system) | | dependency-analyzer | Task dependency wave computation for implement stage dispatch |

9-Stage FSM

specify → specs → design → tasks → implement → review → test → accept → integrate

Each stage has entry/exit criteria in packs/foundation.pack/stages/<stage>/gate.yaml.

Task Lifecycle (v3.1)

Within the implement stage, tasks follow a sub-FSM with a story gate:

  ┌──────────┐     task start      ┌──────────┐
  │ pending  │ ──────────────────→ │ running  │   ← requires complete story
  └──────────┘                     └────┬─────┘
       ▲                               │ task review
       │                          ┌────▼─────┐
       │                          │ reviewing │
       │                          └────┬─────┘
       │                    pass  │    │ fail → fix
       │                    ┌─────┘    └──→ re-review
       │                    ▼
       │              ┌───────────┐
       └──────────────│ completed │ task complete
                      └───────────┘ (only if review passed)

Story Gate: task start refuses to run unless the task's story exists and has no [PLACEHOLDER] markers. No story = no development.

Session Index (v3.1)

Global session CSV at .spec-graph/sessions/sessions.csv:

id,state,description,created_at,updated_at,stage,completed_tasks,pending_tasks,running_tasks,reviewing_tasks,runnable_tasks
fs-20260705-001,running,"Build flash sale...",2026-07-05T09:00:00Z,2026-07-05T10:00:00Z,implement,"user-model","api-docs","auth-endpoints","design-review","request-validation"

Session ID format: <task-abbrev>-<YYYYMMDD>-<NNN> (e.g., fs-20260705-001, auth-20260706-002).

Story System (v3.1)

Each task can have a BMAD-style story document at stories/<task-id>.md:

• Acceptance Criteria — testable criteria for story completion
• Implementation Plan — step-by-step guide
• Pseudocode — core logic flow
• Key Code Snippets — expected file structure and API signatures
• Test Plan — specific test cases
• Definition of Done — completion checklist

Template: packs/foundation.pack/stages/tasks/templates/story.md

API

Workflow Engine

import * as core from '@spec-graph/core';

// Create session with structured ID
const plan = core.automator.startSession('Build user auth', root, { abbrev: 'auth' });
// → sessionId: "auth-20260705-001"

// Confirm plan
core.automator.confirmPlan(plan.sessionId, plan, root);

// Generate dispatch manifest (with task lifecycle steps)
const manifest = core.dispatch.generateDispatchManifest(plan.sessionId, root);

// Submit result for gate evaluation
const result = core.automator.submitResult(plan.sessionId, {
  artifacts: [{ path: '...', content: '...' }]
}, root);
// result.advanced → true | false
// result.diagnosis → { failedCriteria, retryLevel }

// Check status
const status = core.automator.status(plan.sessionId, root);

Task Lifecycle

// Generate stories for all tasks
core.automator.generateTaskStories(sessionId, root);
// → creates .spec-graph/sessions/<id>/stories/<task-id>.md for each task
// → also creates tasks/tasks.md with story links

// Check a story is complete (no [PLACEHOLDER] markers)
const check = core.automator.checkStoryComplete(sessionId, 'user-model', root);
// → { complete: boolean, path: string, missingFields: string[] }

// Check all stories are complete
const checkAll = core.automator.checkAllStoriesComplete(sessionId, root);
// → { allComplete: boolean, incomplete: [...] }

// Start a task (requires complete story at implement stage)
core.automator.startTask(sessionId, 'user-model', root);

// Review a task
const review = core.automator.reviewTask(sessionId, 'user-model', root);
// → { passed: boolean, checks: string[], message: string }

// Complete a task (requires review to pass)
const complete = core.automator.completeTask(sessionId, 'user-model', root);
// → { success: boolean, nextTask: string | null }

Session Index

// List all sessions (reads CSV, auto-migrates legacy dirs)
const rows = core.sessionIndex.list(root);

// Get specific session row
const row = core.sessionIndex.get(root, sessionId);

// Get the latest running session (auto-select)
const latestId = core.automator.getLatestRunningSession(root);

// Reconcile CSV with directories
const report = core.sessionIndex.reconcile(root, { fix: true });

Session Persistence

.spec-graph/
├── sessions/
│   ├── sessions.csv          ← Global session index
│   ├── .migration.log        ← Legacy ID mappings
│   └── <session-id>/
│       ├── state.yaml        ← FSM state + taskStatus + taskReviews
│       ├── stories/          ← Story documents (BMAD-style)
│       │   ├── user-model.md
│       │   └── auth-endpoints.md
│       ├── tasks/
│       │   └── tasks.md      ← Task board with story links
│       ├── specify/proposal.md
│       ├── design/design.md
│       ├── implement/<task-id>.md
│       └── ...
├── config.yaml
└── graph.yaml

Packs

Built-in methodology library shipped with the package:

packs/
└── foundation.pack/
    ├── pack.yaml
    ├── agents/               ← Agent prompt files
    │   └── coordinator-protocol.md
    ├── shared/               ← Shared documents
    └── stages/
        ├── specify/gate.yaml
        ├── design/gate.yaml
        ├── tasks/templates/story.md  ← BMAD story template
        ├── implement/gate.yaml
        └── ... (9 stages)

Users can override by placing files in .spec-graph/pack-overrides.yaml.

Gate Configuration

Each stage has a gate.yaml:

entry:
  - id: plan-confirmed
    description: Plan has been confirmed
    verification: rule

exit:
  - id: proposal-exists
    description: proposal.md has been created
    verification: rule
  - id: capabilities-enumerated
    description: At least one capability
    verification: rule

Verification methods: rule, traceability, llm-judge, downstream-executability, human.

Dispatch Manifest

Lightweight routing manifest — each action contains path pointers:

{
  "id": "user-model",
  "description": "User data model and storage",
  "agent": "/absolute/path/to/developer-agent.md",
  "skills": ["/absolute/path/to/code-generation"],
  "upstream": ["/absolute/path/to/proposal.md"],
  "output": "/absolute/path/to/implement/user-model.md",
  "checks": ["tsc --noEmit"],
  "parallel_group": 0,
  "pre_step": "spec-graph task start user-model --session ...",
  "post_step": "spec-graph task review user-model --session ...",
  "complete_step": "spec-graph task complete user-model --session ..."
}

The pre_step/post_step/complete_step fields appear in implement-stage actions to automate the task lifecycle via the hook chain.

Development

npm install
npm run build    # tsc
npm test         # vitest run (264 tests)

License

MIT