@trieungoctam/speckit 0.2.2 → 0.3.1

package/docs/permission-rules-research.md

@@ -0,0 +1,265 @@
+# Permission Rules Research
+
+Date: 2026-05-10
+
+## Scope
+
+Research goal: define a permission-rule model for Speckit that can compile safely across Claude Code, Codex, Cursor, OpenCode, and Antigravity.
+
+This research focuses on:
+
+- File read/write permissions
+- Shell command permissions
+- Network access
+- Approval modes
+- Phase-specific workflow permissions
+- Enterprise guardrails for secrets, destructive commands, and production access
+
+## Key Findings
+
+### 1. Permission Rules Must Be Deny-First
+
+Claude Code documents allow, ask, and deny rules, with evaluation order `deny -> ask -> allow`; deny rules always take precedence. Cursor CLI also documents deny rules taking precedence over allow rules.
+
+Speckit should use the same mental model across all adapters:
+
+```text
+deny > ask > allow
+```
+
+This should be a product invariant, even when a specific IDE has a different internal matching implementation.
+
+Sources:
+
+- [Claude Code permissions](https://code.claude.com/docs/en/permissions)
+- [Cursor permissions](https://docs.cursor.com/cli/reference/permissions)
+
+### 2. Permissions And Sandboxing Are Different Layers
+
+Claude Code separates permissions from sandboxing: permissions control tool/file/domain access, while sandboxing enforces OS-level limits mainly around shell execution. OpenAI describes the same split for Codex: sandboxing defines execution boundaries, while approval policy decides when the agent must ask.
+
+Speckit should model both layers:
+
+- Permission policy: what the agent may attempt.
+- Sandbox/approval policy: what the runtime may execute without approval.
+
+Sources:
+
+- [Claude Code permissions and sandboxing](https://code.claude.com/docs/en/permissions)
+- [Running Codex safely at OpenAI](https://openai.com/index/running-codex-safely/)
+- [Codex agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
+
+### 3. Avoid Full Bypass Modes Except In Disposable Environments
+
+Claude Code warns that bypass mode skips permission prompts and should only be used in isolated environments such as containers or VMs. Codex similarly labels no-sandbox/no-approval mode as dangerous and not recommended.
+
+Speckit should never generate full-bypass configs by default.
+
+Recommended default:
+
+```text
+approval: ask/on-request
+sandbox: workspace-write
+network: ask or denied by default
+```
+
+Sources:
+
+- [Claude Code permission modes](https://code.claude.com/docs/en/permissions)
+- [Codex common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security)
+
+### 4. Phase-Scoped Permissions Fit Speckit Best
+
+Speckit already has phases: shape, research, plan, context, graph, session, TDD, test, debug, review, docs, ship.
+
+Permission should follow phase, not only IDE:
+
+| Phase | File Writes | Shell | Network | Notes |
+| --- | --- | --- | --- | --- |
+| shape | `.speckit/specs/**` only | ask | ask | No source edits |
+| research | reports/docs only | ask | allow/ask | Sources required |
+| plan | `.speckit/plans/**`, stories, evidence | ask | ask | No source edits |
+| context | `.speckit/context/**` only | ask | deny/ask | Build handoff only |
+| graph | `.speckit/sync/**`, `.beads/**` | allow Speckit wrappers | deny/ask | Robot-safe graph only |
+| session | `.speckit/sessions/**`, memory | ask | deny | Durable state only |
+| TDD | workspace source + tests | ask | ask | Requires ready gate |
+| test | test artifacts only | allow test/build commands | deny/ask | No production |
+| debug | source + tests after root cause | ask | ask | Capture failure first |
+| review | no edits by default | allow `git diff`, `git log`, tests | deny | Read-only review |
+| docs | docs + Speckit artifacts | ask | deny/ask | No source edits unless requested |
+| ship | package/release files | ask | ask | Push/publish/deploy require explicit approval |
+
+### 5. Adapter Mapping
+
+#### Claude Code
+
+Use `.claude/settings.json`:
+
+- `permissions.defaultMode = "ask"` or conservative equivalent
+- explicit deny rules for secrets and destructive commands
+- ask rules for shell/network/publish/deploy
+- optional hooks for runtime validation
+- managed settings for enterprise to disable bypass/auto modes
+
+Relevant details:
+
+- Permission rule syntax supports `Tool` and `Tool(specifier)`.
+- Bash rules support wildcards.
+- Hooks can deny or force prompts before permission rules finish.
+- Managed settings can prevent bypass mode and restrict user/project rules.
+
+Source: [Claude Code permissions](https://code.claude.com/docs/en/permissions)
+
+#### Codex
+
+Use `.codex/config.toml`:
+
+```toml
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+```
+
+Enterprise hardening can use requirements:
+
+```toml
+allowed_approval_policies = ["untrusted", "on-request"]
+allowed_sandbox_modes = ["read-only", "workspace-write"]
+```
+
+Avoid `danger-full-access` and no-approval modes for normal projects.
+
+Sources:
+
+- [Codex config reference](https://developers.openai.com/codex/config-reference)
+- [Codex managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration)
+- [Codex agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
+
+#### Cursor
+
+Use project-level `.cursor/cli.json` for CLI permissions:
+
+```json
+{
+  "permissions": {
+    "allow": ["Shell(git)", "Shell(npm)", "Read(src/**/*.ts)"],
+    "deny": ["Shell(rm)", "Read(.env*)", "Write(**/*.key)", "Write(**/.env*)"]
+  }
+}
+```
+
+Cursor permission tokens cover:
+
+- `Shell(commandBase)`
+- `Read(pathOrGlob)`
+- `Write(pathOrGlob)`
+
+Source: [Cursor permissions](https://docs.cursor.com/cli/reference/permissions)
+
+#### OpenCode
+
+Use `permission` in `opencode.json` and Markdown agents.
+
+OpenCode supports:
+
+- `ask`
+- `allow`
+- `deny`
+- per-agent override
+- specific bash command patterns
+- task permission controls
+
+For Speckit, keep planner/reviewer read-only, TDD developer ask-gated, and ship commands ask-gated.
+
+Source: [OpenCode agents and permissions](https://opencode.ai/docs/agents/)
+
+#### Antigravity
+
+The accessible public docs emphasize configurable autonomy, artifact review, and approval for critical operations, but the browsable official pages did not expose a stable machine-readable permission schema during this research.
+
+Speckit should treat Antigravity permissions as instruction-level until a stable official config format is confirmed:
+
+- generate `.agents/rules/speckit-enterprise-safety.md`
+- require human approval for destructive commands, production changes, secrets access, deployment
+- require artifact review before close
+- avoid claiming hard enforcement unless adapter support is verified
+
+Source:
+
+- [Antigravity agents overview](https://antigravity.im/agents) — independent guide, not official Google documentation
+
+## Recommended Speckit Permission Model
+
+Speckit should own a portable policy and compile it per IDE:
+
+```yaml
+version: 1
+default:
+  file_read: allow_workspace
+  file_write: ask
+  shell: ask
+  network: ask
+  external_directory: deny
+  secrets: deny
+  destructive: deny
+  production: ask
+phases:
+  review:
+    file_write: deny
+    shell_allow:
+      - git diff*
+      - git log*
+      - npm test*
+  ship:
+    shell_ask:
+      - git push*
+      - npm publish*
+      - "* deploy*"
+```
+
+## Commands To Add
+
+Recommended CLI surface:
+
+```bash
+speckit permissions init
+speckit permissions audit --json
+speckit permissions compile --ide all
+speckit validate --permissions --json
+```
+
+Minimum useful implementation:
+
+1. Generate `.speckit/permissions.yaml`.
+2. Add permission checks to `speckit validate`.
+3. Compile:
+   - Claude Code: `.claude/settings.json`
+   - Codex: `.codex/config.toml`
+   - Cursor: `.cursor/cli.json`
+   - OpenCode: `opencode.json` and agent frontmatter
+   - Antigravity: `.agents/rules/speckit-enterprise-safety.md`
+
+## High-Risk Defaults To Block
+
+Always deny or ask:
+
+- `rm -rf`, `rmdir`, destructive cleanup
+- `git reset --hard`, `git clean -fd`, force push
+- `sudo`, `chmod -R`, `chown -R`
+- shell access to `.env*`, `*.pem`, `*.key`, SSH keys, cloud credentials
+- production deploys
+- package publish
+- arbitrary outbound network from shell
+- external directory writes
+
+## Recommendation
+
+Implement permission rules as the next Speckit enterprise layer.
+
+Priority:
+
+1. Add central `.speckit/permissions.yaml`.
+2. Extend `validateWorkflowContract` with permission checks.
+3. Compile concrete adapter permission files.
+4. Add tests that tamper with dangerous permissions and ensure validation fails.
+
+This keeps Speckit aligned with the strongest common pattern across current agent IDEs: deny-first, least-privilege, phase-scoped, with explicit approval for risky operations.

package/docs/product-contract.md

@@ -5,23 +5,28 @@ Speckit owns the workflow contract for enterprise Agile + TDD development with a
 ## Speckit Owns
 
 - The `.speckit/` source of truth: config, rules, workflows, templates, generated artifacts.
-- The command surface: `init`, `doctor`, `start`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `next`, `ready`, `run`, `review`, `close`.
+- The command surface: `init`, `doctor`, `validate`, `start`, `memory`, `permissions`, `session`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `sprint`, `graph`, `next`, `ready`, `run`, `review`, `close`.
+- The skill catalog and super-agent routing contract for phase-specific agent behavior.
+- IDE-specific initialization that installs the shared Speckit runtime plus only the selected IDE adapter when `--ide <name>` is provided.
+- The long-session contract: project memory, active session state, checkpoints, compaction summaries, and resume handoffs.
+- The workflow validation contract: phase order, core skills, super-agent routing, run prompt terms, and installed adapter prompt parity.
 - The TDD gate: code stories require red, green, and refactor evidence.
 - The adapter compiler for Claude Code, Codex, Antigravity, OpenCode, and Cursor.
 - The safety policy for destructive commands, secrets, production access, and review readiness.
+- The permission policy for privacy-sensitive files, context-heavy paths, destructive commands, and release commands.
 
 ## Speckit Delegates
 
 - Implementation to the selected IDE and agent runtime.
 - Product lifecycle, story readiness, and quality gates to Speckit-native phases.
 - Execution orchestration to Speckit-native plan/run/test/review flows.
-- Task graph prioritization to beads and Beads Viewer robot commands.
+- Task graph prioritization to beads and Beads Viewer robot commands, with local JSON fallback when `bv` is unavailable.
 - Git, tests, CI, and deployment to project-local tooling.
 
 ## State Model
 
 ```text
-intake -> session -> shaped -> planned -> context-ready -> synced -> triaged -> ready-for-dev -> tests-red -> running -> tests-green -> refactor -> review-ready -> closed
+intake -> session -> memory-ready -> shaped -> planned -> sprint-ready -> context-ready -> synced -> graph-triaged -> ready-for-dev -> tests-red -> checkpointed -> running -> tests-green -> refactor -> compacted -> review-ready -> closed
 ```
 
-Implementation starts only after `speckit ready <story>` passes. Review starts only after test evidence exists.
+Implementation starts only after `speckit ready <story>` passes. Review starts only after test evidence exists and the active session has a current checkpoint.

package/docs/project-changelog.md

@@ -1,5 +1,51 @@
 # Project Changelog
 
+## 0.3.1 - 2026-05-11
+
+### Changed
+
+- Prepared npm release for the workflow validation and permission policy package updates.
+
+### Validation
+
+- `npm test` passes with 36 tests.
+
+## 0.3.0 - 2026-05-10
+
+### Added
+
+- Added `speckit memory refresh` for durable project context, decisions, and lessons.
+- Added `speckit session start`, `checkpoint`, `compact`, `resume`, and `status`.
+- Added `speckit sprint plan` and `speckit sprint next` from synced stories.
+- Added `speckit graph triage`, `graph plan`, and `graph insights` with Beads Viewer robot mode and local JSON fallback.
+- Added `.speckit/agents/super-agent.md` as the portable orchestration router.
+- Added `.speckit/skills/catalog.md` plus a curated Speckit skill set for shape, research, plan, context, graph, session, TDD, test, debug, review, docs, and ship phases.
+- Added `.speckit/skills/schema.json` to define the portable skill contract and delegation statuses.
+- Added `speckit validate` for workflow contract validation across phase order, skills, router, prompts, and installed adapters.
+- Added `contractChecks` to `speckit doctor --deep --json`.
+- Added `docs/use-cases.md` with command recipes and best practices for setup, migration, quick changes, full planning, long sessions, TDD, graph automation, review, CI, and troubleshooting.
+- Added `.speckit/permissions.yaml` and `speckit permissions audit` for privacy, scout, destructive-command, and release-command checks.
+- Added concrete permission output for Claude Code, Codex, and Cursor adapters.
+- Added long-session prompt requirements for project memory, active session state, checkpoints, and compaction summaries.
+- Added automatic `.beads/beads.jsonl` mirror generation so Beads Viewer robot commands can run without missing-project errors.
+- Standard `speckit init --ide <name>` now installs the shared Speckit runtime, super-agent, and skill catalog for the selected IDE.
+
+### Changed
+
+- Enterprise flow now includes memory, sprint planning, graph triage, readiness, checkpoint, and compaction phases.
+- Enterprise adapters now route through the Speckit super agent and smallest matching skill before execution.
+- Super-agent routing now includes delegation status, task hydration, and sync-back contracts adapted from long-session orchestration patterns.
+- IDE adapters now instruct agents to checkpoint red-green-refactor boundaries and compact before handoff.
+- `speckit graph triage|plan|insights` now prepares the Beads Viewer mirror before invoking `bv --robot-*` from the project root.
+- Selected-IDE init now avoids unrelated IDE adapters while still installing shared runtime files.
+
+### Quality
+
+- Added workflow tests for memory/session state, sprint planning, and graph fallback.
+- Expanded prompt quality tests for project memory, active session, checkpoint, and compaction.
+- Added init and flow contract coverage for the curated skill catalog.
+- Added workflow validator tests for passing and tampered contract states.
+
 ## 0.2.2 - 2026-05-10
 
 ### Added

package/docs/spec-enterprise-harness-plan.md

@@ -11,11 +11,15 @@ The product vocabulary is Spec-only. External tools may exist underneath, but ge
 ```text
 idea
   -> spec start
+  -> super-agent route
+  -> spec memory
   -> spec shape
   -> spec plan
+  -> spec sprint
   -> spec context
   -> graph triage
   -> spec run
+  -> spec checkpoint
   -> spec review
   -> spec close
 ```
@@ -26,7 +30,10 @@ idea
 | --- | --- | --- |
 | Spec Flow | Phase order and state transitions | `.speckit/flows/*.md` |
 | Spec Prompt | Phase-specific instructions | `.speckit/prompts/**/*.md` |
+| Spec Super Agent | Phase routing and orchestration policy | `.speckit/agents/super-agent.md` |
+| Spec Skills | Focused phase capabilities loaded on demand | `.speckit/skills/*.md` |
 | Spec Session | Durable continuity across agents | `.speckit/sessions/<id>/*` |
+| Spec Memory | Durable project rules and lessons | `.speckit/memory/*` |
 | Spec Context | Bounded task context | `.speckit/context/current.md` |
 | Spec Tool | Phase-aware allowed/denied actions | `.speckit/tool-policy.yaml` |
 | Spec Graph | Work queue and priority bridge | `.speckit/graph/*` |
@@ -38,8 +45,14 @@ idea
 speckit init --enterprise --ide all
 speckit doctor --deep
 speckit start "<idea>"
+speckit memory refresh
+speckit session checkpoint
+speckit session compact
+speckit session resume
 speckit shape "<idea>"
 speckit plan "<feature>"
+speckit sprint plan
+speckit graph triage
 speckit context <story-or-bead>
 speckit triage
 speckit next
@@ -53,7 +66,10 @@ speckit sync
 
 - Forbidden legacy vocabulary must not appear in publishable source, docs, tests, prompts, or generated adapter templates.
 - Every implementation story must link to acceptance criteria and TDD evidence.
+- Every agent run must route through the super-agent policy and the smallest matching Speckit skill.
 - Every run must have a session handoff.
+- Every long run must checkpoint after red, green, refactor, and review boundaries.
+- Every handoff must have a compact session summary when context has grown noisy.
 - Every graph task must trace back to a story or spec artifact.
 - Every review must check AC coverage, TDD evidence, tool policy, and docs impact.
 - All robot task graph commands must use non-interactive flags.
@@ -61,8 +77,9 @@ speckit sync
 ## Definition Of Enterprise Ready
 
 - `speckit init --enterprise --ide all` creates a complete harness in a temp repo.
+- The generated harness includes `.speckit/agents/super-agent.md` and `.speckit/skills/catalog.md`.
 - `speckit doctor --deep --json` returns stable machine-readable status.
-- `speckit start -> context -> run -> review -> close` preserves a single session id.
+- `speckit start -> session checkpoint -> session compact -> context -> run -> review -> close` preserves a single session id.
 - `speckit sync -> triage -> next` preserves story-to-graph traceability.
 - All IDE adapters compile from the same Spec policies.
 - Tests enforce vocabulary, flow links, adapter parity, and robot-safe graph commands.

package/docs/use-cases.md

@@ -0,0 +1,206 @@
+# Use Cases And Best Practices
+
+This guide shows how to use Speckit for common product and engineering workflows.
+
+## 1. New Project Setup
+
+Use when a repository does not have Speckit runtime files yet.
+
+```bash
+npx @trieungoctam/speckit@latest init --enterprise --ide cursor
+npx @trieungoctam/speckit@latest doctor --deep
+npx @trieungoctam/speckit@latest validate
+```
+
+Use `--ide all` only when the team actively uses multiple IDEs in the same repository.
+
+Best practices:
+
+- Prefer one IDE adapter per project at first. Add more adapters after the team agrees on the workflow.
+- Run `speckit validate` after init so broken prompts or missing skills are caught immediately.
+- Commit generated Speckit files so every teammate gets the same flow.
+- Keep `.speckit/` local to the repository. Avoid relying on global agent state for enterprise work.
+
+## 2. Existing Project Migration
+
+Use when a project already has code, tests, and team conventions.
+
+```bash
+speckit init --enterprise --ide all --force
+speckit memory refresh
+speckit doctor --deep --json
+speckit validate --json
+```
+
+Best practices:
+
+- Read generated files before pushing. Keep project-specific rules in `.speckit/memory/project-context.md`.
+- Do not start implementation during migration. First make the generated flow pass validation.
+- If an adapter prompt conflicts with local policy, update the adapter generator, not only the generated file.
+- Run project tests after migration even if Speckit only changed documentation and prompt files.
+
+## 3. One Small Change
+
+Use when the request is bounded and can fit into one story.
+
+```bash
+speckit memory refresh
+speckit session start "Add invoice total validation"
+speckit quick "Add invoice total validation"
+speckit context .speckit/stories/<story>.md
+speckit sync
+speckit ready .speckit/stories/<story>.md
+speckit run .speckit/stories/<story>.md
+```
+
+Best practices:
+
+- Use `quick` only for a single focused change.
+- Do not skip `context`, `sync`, or `ready`. They prevent agents from implementing against stale assumptions.
+- Keep acceptance criteria concrete enough to test.
+- Checkpoint after the red test, green test, refactor, and review boundary.
+
+## 4. Full Feature Planning
+
+Use when the work includes multiple stories, architecture decisions, or team rollout.
+
+```bash
+speckit session start "Add subscription lifecycle"
+speckit memory refresh
+speckit shape "Add subscription lifecycle"
+speckit plan "Add subscription lifecycle"
+speckit sync
+speckit sprint plan
+speckit graph triage --json
+```
+
+Best practices:
+
+- Shape before planning. The shape artifact defines scope, non-goals, and risk.
+- Keep stories small enough to pass through TDD evidence independently.
+- Sync stories before graph commands so prioritization uses current metadata.
+- Use `sprint next` or `graph triage` to select work instead of choosing only by recency.
+
+## 5. Long Agent Session
+
+Use when work will span many tool calls, handoffs, or context compaction.
+
+```bash
+speckit memory refresh
+speckit session start "Refactor report export flow"
+speckit session status --json
+speckit session checkpoint --note "red complete"
+speckit session checkpoint --note "green complete"
+speckit session compact
+speckit session resume <session-id>
+```
+
+Best practices:
+
+- Durable files are the source of truth, not chat history.
+- Write decisions to memory when they apply beyond the current story.
+- Compact before handing work to another agent or after noisy command output.
+- Use `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, or `NEEDS_CONTEXT` in handoffs.
+- Never pass a full conversation as handoff context. Pass files, acceptance criteria, constraints, and current status.
+
+## 6. TDD Implementation
+
+Use for all code stories.
+
+```bash
+speckit ready .speckit/stories/<story>.md
+speckit run .speckit/stories/<story>.md
+npm test
+speckit session checkpoint --note "red evidence captured"
+npm test
+speckit session checkpoint --note "green evidence captured"
+speckit session checkpoint --note "refactor validated"
+```
+
+Best practices:
+
+- Record test intent before code changes.
+- Capture the red result before implementation.
+- Make the smallest change that turns the failing test green.
+- Refactor only while tests stay green.
+- Put command output summaries in the evidence file. Avoid pasting large logs unless they are necessary.
+
+## 7. Graph And Sprint Automation
+
+Use when multiple stories exist and the next task is not obvious.
+
+```bash
+speckit sync
+speckit sprint plan
+speckit sprint next --json
+speckit graph triage --json
+speckit graph plan --json
+speckit graph insights --json
+```
+
+Best practices:
+
+- Run `sync` before any graph command.
+- Keep graph commands robot-safe. Use Speckit wrappers instead of interactive graph commands.
+- Treat graph output as prioritization input, not automatic permission to implement.
+- Re-run `sprint plan` when story status or dependencies change.
+
+## 8. Review And Closure
+
+Use after implementation and tests pass.
+
+```bash
+speckit review
+speckit session compact
+speckit close .speckit/stories/<story>.md
+speckit sync
+speckit validate
+```
+
+Best practices:
+
+- Review acceptance coverage before style or preference issues.
+- Check TDD evidence, session freshness, docs impact, and graph sync.
+- Close only after the story has current evidence and a clean handoff.
+- Sync after closing so downstream graph and sprint views are current.
+
+## 9. CI And Enterprise Rollout
+
+Use when Speckit becomes a shared team standard.
+
+Recommended CI checks:
+
+```bash
+npm run build
+npm test
+npx @trieungoctam/speckit@latest doctor --deep --json
+npx @trieungoctam/speckit@latest validate --json
+```
+
+Best practices:
+
+- Fail CI when `validate` returns `needs-attention`.
+- Require `doctor --deep` before release branches are merged.
+- Keep generated prompt files reviewed like source code.
+- Add new workflow phases only through the central contract and tests.
+- Do not allow IDE-specific prompts to drift from the shared Speckit contract.
+
+## 10. Troubleshooting
+
+Use these checks when the workflow feels inconsistent.
+
+```bash
+speckit doctor --deep --json
+speckit validate --json
+speckit session status --json
+speckit sync
+speckit graph triage --json
+```
+
+Common fixes:
+
+- Missing skill file: run `speckit init --enterprise --ide <name> --force`.
+- Adapter prompt mismatch: update the adapter generator, rebuild, then init again.
+- Story is blocked: run `speckit context <story>` and `speckit sync`, then retry `speckit ready <story>`.
+- Graph command fails: check that `.beads/beads.jsonl` exists after `speckit sync`.
+- Session context is stale: run `speckit session checkpoint` and `speckit session compact`.

package/docs/workflow-model.md

@@ -8,7 +8,10 @@ Use for a bounded change.
 
 ```bash
 speckit quick "Add invoice validation"
+speckit memory refresh
+speckit session start "Add invoice validation"
 speckit run .speckit/stories/<story>.md
+speckit session checkpoint --note "story implemented"
 speckit review
 ```
 
@@ -16,6 +19,8 @@ Outputs:
 
 - `.speckit/stories/<story>.md`
 - `.speckit/evidence/<story>-tdd-evidence.md`
+- `.speckit/sessions/<session>/summary.md`
+- `.speckit/sessions/<session>/artifact-log.md`
 
 ## Full Lane
 
@@ -25,6 +30,8 @@ Use for product or enterprise rollout work.
 speckit shape "Standardize Agile + TDD across teams"
 speckit plan "Standardize Agile + TDD across teams"
 speckit sync
+speckit sprint plan
+speckit graph triage --json
 speckit next
 ```
 
@@ -36,6 +43,9 @@ Outputs:
 - `.speckit/plans/<plan>/story.md`
 - `.speckit/plans/<plan>/tdd-evidence.md`
 - `.speckit/sync/beads-sync.jsonl`
+- `.beads/beads.jsonl`
+- `.speckit/sprint/status.yaml`
+- `.speckit/sprint/plan.md`
 
 ## TDD Evidence Gate
 
@@ -47,3 +57,16 @@ Each code story must record:
 - Refactor command and result
 
 Missing evidence means the story is not review-ready.
+
+## Long Session Gate
+
+Long-running agent work must keep durable state outside chat history:
+
+- `.speckit/memory/project-context.md` stores project-wide implementation rules.
+- `.speckit/sessions/active.md` points to the active session.
+- `.speckit/sessions/<id>/artifact-log.md` records checkpoints and files touched.
+- `.speckit/sessions/<id>/summary.md` is the compacted handoff for resume.
+
+## Beads Viewer Automation
+
+`speckit sync` prepares both Speckit sync metadata and a Beads Viewer-compatible `.beads/beads.jsonl` mirror. `speckit graph triage|plan|insights` refreshes that mirror before invoking `bv --robot-*` from the project root, then falls back to local JSON if Beads Viewer is unavailable or still fails.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trieungoctam/speckit",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Enterprise Agile + TDD workflow compiler for agentic IDEs.",
   "type": "module",
   "files": [