@trieungoctam/speckit 0.3.0 → 0.3.3

package/docs/prompt-architecture.md

@@ -0,0 +1,88 @@
+<!-- speckit:managed -->
+# Speckit Prompt Architecture
+
+Speckit prompts are product contracts, not loose instructions. Each prompt must make the agent produce durable Agile + TDD artifacts that another agent can resume, validate, and review.
+
+## Design Goals
+
+- Keep rough intent separate from implementation.
+- Make acceptance criteria and TDD evidence first-class.
+- Preserve long-session continuity through files.
+- Keep IDE prompts aligned across all supported tools.
+- Prefer machine-checkable output over conversational claims.
+
+## Prompt Layers
+
+| Layer | Purpose | Example Artifact |
+| --- | --- | --- |
+| Router | Select the smallest matching skill | `.speckit/agents/super-agent.md` |
+| Skill | Define phase-specific behavior | `.speckit/skills/spec-tdd.md` |
+| Workflow | Define ordered phase execution | `.speckit/workflows/tdd-run.md` |
+| Run prompt | Define implementation contract | `.speckit/prompts/spec-run.md` |
+| IDE adapter | Project the same contract into each tool | `AGENTS.md`, `.claude/skills/*`, `.cursor/rules/*` |
+
+## Required Prompt Sections
+
+Every core prompt should include:
+
+- Goal
+- Phase or role
+- Required context
+- Inputs and outputs
+- Hard gates
+- Common mistakes to prevent
+- Stop conditions
+- Output contract
+- Validation command or evidence requirement
+
+## Implementation Prompt Contract
+
+Code-producing prompts must require:
+
+- Ready story with acceptance criteria.
+- Fresh current context.
+- Active session.
+- Matching TDD evidence path.
+- Red evidence before implementation.
+- Green evidence after the target test passes.
+- Refactor evidence after regression validation.
+- Story Dev Agent Record, File List, and Change Log updates.
+- Session checkpoint at red, green, refactor, and review boundaries.
+
+## Review Prompt Contract
+
+Review prompts run in this order:
+
+1. Spec compliance: requested behavior, AC coverage, and no unrelated scope.
+2. Edge-case pathing: branch, boundary, error, state, and concurrency gaps.
+3. Production readiness: security, compatibility, performance, observability, rollback, docs.
+
+Findings lead the report. Each finding needs severity, path, impact, and concrete fix.
+
+## Long Session Contract
+
+- Keep durable decisions in `.speckit/**`, not chat.
+- Load only the current phase and directly referenced files.
+- Compact before handoff or after noisy tool output.
+- Preserve session summary and artifact log.
+- Rehydrate from project memory, active session, current context, story, and evidence.
+
+## Adapter Policy
+
+All IDE adapters must preserve the same terms:
+
+- project memory
+- active session
+- current context
+- subagent handoff
+- acceptance criteria
+- red-green-refactor
+- checkpoint and compact
+- robot-safe graph commands
+- ready-for-dev
+- Dev Agent Record
+- File List
+- Change Log
+- spec compliance
+- edge-case review
+

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/package.json

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