@trieungoctam/speckit 0.3.6 → 0.4.1

package/README.md

@@ -10,11 +10,18 @@ The curated skill set is intentionally small: `spec-shape`, `spec-research`, `sp
 
 ## Quickstart
 
+Recommended enterprise setup:
+
 ```bash
 npx @trieungoctam/speckit@latest setup
-npx @trieungoctam/speckit@latest init --ide cursor
-npx @trieungoctam/speckit@latest init --ide all
-npx @trieungoctam/speckit@latest init --enterprise --ide all
+npx @trieungoctam/speckit@latest doctor --deep
+npx @trieungoctam/speckit@latest validate
+npx @trieungoctam/speckit@latest score
+```
+
+One story end-to-end:
+
+```bash
 npx @trieungoctam/speckit@latest memory refresh
 npx @trieungoctam/speckit@latest session start "Add checkout validation"
 npx @trieungoctam/speckit@latest quick "Add checkout validation"
@@ -23,6 +30,10 @@ npx @trieungoctam/speckit@latest sync
 npx @trieungoctam/speckit@latest graph setup
 npx @trieungoctam/speckit@latest sprint plan
 npx @trieungoctam/speckit@latest graph triage --json
+npx @trieungoctam/speckit@latest team status .speckit/stories/<story>.md
+npx @trieungoctam/speckit@latest team audit .speckit/stories/<story>.md --json
+npx @trieungoctam/speckit@latest team handoff .speckit/stories/<story>.md --from dev --to qa
+npx @trieungoctam/speckit@latest score .speckit/stories/<story>.md
 npx @trieungoctam/speckit@latest validate --json
 npx @trieungoctam/speckit@latest permissions audit --path .env --json
 npx @trieungoctam/speckit@latest ready .speckit/stories/<story>.md
@@ -30,6 +41,13 @@ npx @trieungoctam/speckit@latest session checkpoint --note "red complete"
 npx @trieungoctam/speckit@latest review
 ```
 
+Reset repo-local adapters before reinstalling:
+
+```bash
+rm -rf .claude CLAUDE.md .codex AGENTS.md .cursor .opencode opencode.json
+npx @trieungoctam/speckit@latest setup
+```
+
 Interactive CLI output is colorized when the terminal supports ANSI colors. Use `NO_COLOR=1` to disable colors, or `SPECKIT_COLOR=1` to force colors for demos and snapshots.
 
 Or install globally:
@@ -85,6 +103,11 @@ For implementation stories, red-green-refactor evidence is mandatory. A story is
 | `speckit session compact` | Create an anchored summary for resume or handoff. |
 | `speckit session resume` | Mark a session as active and print its handoff path. |
 | `speckit session status` | Print active session state paths. |
+| `speckit team status <story>` | Show role-by-role team artifact readiness for a story. |
+| `speckit team audit <story>` | Run enterprise review-gate checks and return nonzero when blockers remain. |
+| `speckit team handoff <story>` | Create a durable role-to-role handoff artifact. |
+| `speckit score` | Score project workflow health across contract, team model, context/session, and graph sync. |
+| `speckit score <story>` | Score story health across team readiness, developer trace, TDD evidence, and review gate. |
 | `speckit shape "<intent>"` | Create a short spec contract. |
 | `speckit context <story>` | Build the current implementation context from a story. |
 | `speckit quick "<intent>"` | Create one story plus matching TDD evidence file. |
@@ -117,7 +140,9 @@ See `docs/adapters.md` for exact output paths.
 
 ## Guides
 
+- `docs/getting-started.md` covers setup, adapter reset, verification, story execution, team audit, and close.
 - `docs/use-cases.md` covers setup, migration, quick changes, full planning, long sessions, TDD, graph automation, review, CI, and troubleshooting.
+- `docs/team-workflow.md` covers enterprise role ownership, status, audit, and handoff flow.
 - `docs/beads-viewer-setup.md` covers Beads Viewer installation, `bv` verification, and robot-safe graph usage.
 - `docs/workflow-model.md` describes the quick and full workflow lanes.
 - `docs/prompt-architecture.md` describes the prompt contract used by the super-agent, skills, workflows, run prompt, and IDE adapters.

package/dist/cli.js

@@ -9,6 +9,8 @@ import { planCommand } from "./commands/plan.js";
 import { memoryCommand } from "./commands/memory.js";
 import { permissionsCommand } from "./commands/permissions.js";
 import { sessionCommand } from "./commands/session.js";
+import { teamCommand } from "./commands/team.js";
+import { scoreCommand } from "./commands/score.js";
 import { sprintCommand } from "./commands/sprint.js";
 import { graphCommand } from "./commands/graph.js";
 import { validateCommand } from "./commands/validate.js";
@@ -66,6 +68,21 @@ export async function main(argv = process.argv.slice(2), root = process.cwd()) {
                     note: value(parsed, "note"),
                     json: has(parsed, "json"),
                 });
+            case "team":
+                return teamCommand({
+                    root,
+                    action: requiredAction(parsed),
+                    target: parsed.args.slice(1).join(" ").trim() || undefined,
+                    from: value(parsed, "from"),
+                    to: value(parsed, "to"),
+                    json: has(parsed, "json"),
+                });
+            case "score":
+                return scoreCommand({
+                    root,
+                    target: parsed.args.join(" ").trim() || undefined,
+                    json: has(parsed, "json"),
+                });
             case "sprint":
                 return sprintCommand({ root, action: requiredAction(parsed), json: has(parsed, "json") });
             case "graph":
@@ -162,6 +179,8 @@ Usage:
   speckit memory refresh
   speckit permissions audit [--path <path>] [--command <command>] [--json]
   speckit session start|checkpoint|compact|resume|status [target] [--note "..."] [--json]
+  speckit team status|audit|handoff <story-path-or-id> [--from <role>] [--to <role>] [--json]
+  speckit score [story-path-or-id] [--json]
   speckit sprint plan|next [--json]
   speckit graph setup|triage|plan|insights [--json]
   speckit validate [--json]

package/dist/commands/plan.js

@@ -40,16 +40,49 @@ export async function planCommand(options) {
 evidence: ${dir}/tdd-evidence.md
 context: pending`, `# Story: ${options.intent}
 
+## Business Goal
+- Goal: ${options.intent}
+- Priority: medium
+- Success signal:
+
 ## Acceptance Criteria
 - Given ...
 - When ...
 - Then ...
 
+## Edge Cases
+- Boundary:
+- Error path:
+- State transition:
+
+## Implementation Scope
+- In scope:
+- Out of scope:
+- Files likely to read:
+- Files likely to modify:
+
+## Architecture Notes
+- Constraints:
+- Integration points:
+- Risks:
+
 ## TDD Evidence File
 \`${dir}/tdd-evidence.md\`
 
 ## Implementation Notes
 
+## Dev Agent Record
+### Test Intent
+
+### Debug Log
+
+### Completion Notes
+
+### File List
+
+## Change Log
+- ${new Date().toISOString().slice(0, 10)}: Story drafted.
+
 ## Spec Anti-Mistake Checklist
 - Reuse existing project patterns before adding new files.
 - Verify file locations before editing.
@@ -62,11 +95,15 @@ context: pending`, `# Story: ${options.intent}
             content: markdownWithFrontmatter(`status: missing
 story: ${dir}/story.md`, `# TDD Evidence: ${options.intent}
 
+## Test Intent
+
 ## Red
 
 ## Green
 
 ## Refactor
+
+## Review Evidence
 `),
         },
     ];

package/dist/commands/quick.js

@@ -18,11 +18,32 @@ context: pending`, `# Story: ${options.intent}
 ## Intent
 ${options.intent}
 
+## Business Goal
+- Goal: ${options.intent}
+- Priority: medium
+- Success signal: behavior is covered by executable tests and Speckit evidence
+
 ## Acceptance Criteria
 - Given the current product state
 - When this story is implemented
 - Then the behavior is covered by executable tests and Speckit evidence
 
+## Edge Cases
+- Boundary: document the smallest input, state, or permission boundary this story touches.
+- Error path: document how failures are surfaced or recovered.
+- State transition: document before and after behavior.
+
+## Implementation Scope
+- In scope: the smallest change needed to satisfy the acceptance criteria.
+- Out of scope: unrelated refactors, new dependencies, or behavior not tied to acceptance criteria.
+- Files likely to read:
+- Files likely to modify:
+
+## Architecture Notes
+- Constraints: reuse existing project patterns before adding new abstractions.
+- Integration points:
+- Risks:
+
 ## TDD Checklist
 - [ ] Test target identified
 - [ ] Red evidence recorded in ${evidencePath}
@@ -38,6 +59,18 @@ ${options.intent}
 - Do not introduce new libraries without explicit need.
 - Preserve existing behavior unless an acceptance criterion requires change.
 - Update docs only when behavior or workflow changes.
+
+## Dev Agent Record
+### Test Intent
+
+### Debug Log
+
+### Completion Notes
+
+### File List
+
+## Change Log
+- ${new Date().toISOString().slice(0, 10)}: Story drafted.
 `),
         },
         {
@@ -58,6 +91,11 @@ story: ${storyPath}`, `# TDD Evidence: ${options.intent}
 ## Refactor
 - Command: \`${testCommand}\`
 - Result:
+
+## Review Evidence
+- Reviewer:
+- Outcome:
+- Follow-ups:
 `),
         },
     ]);

package/dist/commands/score.d.ts

@@ -0,0 +1,7 @@
+export type ScoreOptions = {
+    root: string;
+    target?: string;
+    json?: boolean;
+    stdout?: Pick<typeof console, "log">;
+};
+export declare function scoreCommand(options: ScoreOptions): Promise<number>;

package/dist/commands/score.js

@@ -0,0 +1,29 @@
+import { createColors } from "../core/colors.js";
+import { calculateSpecScore } from "../core/spec-score.js";
+export async function scoreCommand(options) {
+    const stdout = options.stdout ?? console;
+    const report = await calculateSpecScore(options.root, options.target);
+    stdout.log(options.json ? JSON.stringify(report, null, 2) : renderScore(report));
+    return report.status === "blocked" ? 1 : 0;
+}
+function renderScore(report) {
+    const colors = createColors();
+    const lines = [
+        `${colors.bold("Spec Runtime Score")}: ${colors.status(report.score >= 75, `${report.score}/100`, `${report.score}/100`)}`,
+        `Status: ${report.status}`,
+    ];
+    if (report.target)
+        lines.push(`Target: ${colors.cyan(report.target)}`);
+    lines.push("");
+    for (const category of report.categories) {
+        const ok = category.score >= 75;
+        lines.push(`${colors.status(ok, String(category.score), String(category.score)).padStart(colors.enabled ? 12 : 3)} ${category.name}: ${category.passed}/${category.total} - ${category.detail}`);
+    }
+    lines.push("", "Recommendations:");
+    lines.push(...report.recommendations.map((item) => `- ${item}`));
+    if (report.blockers.length) {
+        lines.push("", "Blockers:");
+        lines.push(...report.blockers.map((item) => `- ${item}`));
+    }
+    return lines.join("\n");
+}

package/dist/commands/team.d.ts

@@ -0,0 +1,10 @@
+export type TeamOptions = {
+    root: string;
+    action: string;
+    target?: string;
+    from?: string;
+    to?: string;
+    json?: boolean;
+    stdout?: Pick<typeof console, "log" | "error">;
+};
+export declare function teamCommand(options: TeamOptions): Promise<number>;

package/dist/commands/team.js

@@ -0,0 +1,129 @@
+import { buildTeamReport } from "../core/team-report.js";
+import { createColors } from "../core/colors.js";
+import { markdown, writeManagedFiles } from "../core/managed-files.js";
+import { slugify, timestamp } from "../core/slug.js";
+export async function teamCommand(options) {
+    const stdout = options.stdout ?? console;
+    switch (options.action) {
+        case "status":
+            return status(options);
+        case "audit":
+            return audit(options);
+        case "handoff":
+            return handoff(options);
+        default:
+            stdout.error("Usage: speckit team status|audit|handoff <story> [--from <role>] [--to <role>] [--json]");
+            return 1;
+    }
+}
+async function status(options) {
+    const stdout = options.stdout ?? console;
+    const target = requireTarget(options);
+    if (!target)
+        return 1;
+    const report = await buildTeamReport(options.root, target);
+    stdout.log(options.json ? JSON.stringify(report, null, 2) : renderReport(report, "Spec Team Status"));
+    return report.story ? 0 : 1;
+}
+async function audit(options) {
+    const stdout = options.stdout ?? console;
+    const target = requireTarget(options);
+    if (!target)
+        return 1;
+    const report = await buildTeamReport(options.root, target);
+    const auditReport = {
+        gate: "review",
+        status: report.status,
+        story: report.story,
+        blockers: report.blockers,
+        warnings: report.warnings,
+        roles: report.roles,
+    };
+    stdout.log(options.json ? JSON.stringify(auditReport, null, 2) : renderAudit(auditReport));
+    return report.status === "ok" ? 0 : 1;
+}
+async function handoff(options) {
+    const stdout = options.stdout ?? console;
+    const target = requireTarget(options);
+    if (!target)
+        return 1;
+    const report = await buildTeamReport(options.root, target);
+    if (!report.story) {
+        stdout.error(report.blockers[0] ?? `Story not found: ${target}`);
+        return 1;
+    }
+    const from = options.from ?? "current-role";
+    const to = options.to ?? "next-role";
+    const path = `.speckit/team/handoffs/${timestamp()}-${slugify(report.story.id)}-${slugify(from)}-to-${slugify(to)}.md`;
+    await writeManagedFiles(options.root, [
+        {
+            path,
+            content: markdown(`# Spec Team Handoff
+
+## Story
+\`${report.story.path}\`
+
+## Route
+- From: ${from}
+- To: ${to}
+
+## Current Status
+- Story status: ${report.story.status ?? "missing"}
+- Team status: ${report.status}
+
+## Blockers
+${report.blockers.length ? report.blockers.map((item) => `- ${item}`).join("\n") : "- none"}
+
+## Warnings
+${report.warnings.length ? report.warnings.map((item) => `- ${item}`).join("\n") : "- none"}
+
+## Next Role Checklist
+- [ ] Read the story and linked evidence file.
+- [ ] Resolve blockers owned by the target role.
+- [ ] Update durable artifacts before handing off again.
+- [ ] Run \`speckit team audit ${report.story.path}\`.
+`),
+        },
+    ]);
+    stdout.log(path);
+    return 0;
+}
+function renderReport(report, title) {
+    const colors = createColors();
+    if (!report.story)
+        return `${colors.bold(title)}: ${colors.red("blocked")}\n${report.blockers.join("\n")}`;
+    const lines = [
+        `${colors.bold(title)}: ${colors.status(report.status === "ok", "ok", "blocked")}`,
+        `Story: ${colors.cyan(report.story.path)}`,
+        `State: ${report.story.status ?? "missing"}`,
+        "",
+    ];
+    for (const role of report.roles) {
+        lines.push(`${colors.bold(role.role)}: ${colors.status(role.status === "ok", role.status, role.status)}`);
+        for (const check of role.checks) {
+            lines.push(`  - ${colors.status(check.ok)} ${check.name}: ${check.detail}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+function renderAudit(report) {
+    const colors = createColors();
+    return [
+        `${colors.bold("Spec Team Audit")}: ${colors.status(report.status === "ok", "ok", "blocked")}`,
+        `Gate: ${report.gate}`,
+        report.story ? `Story: ${colors.cyan(report.story.path)}` : undefined,
+        "",
+        "Blocking:",
+        ...(report.blockers.length ? report.blockers.map((item) => `- ${item}`) : ["- none"]),
+        "",
+        "Warnings:",
+        ...(report.warnings.length ? report.warnings.map((item) => `- ${item}`) : ["- none"]),
+    ].filter((line) => line !== undefined).join("\n");
+}
+function requireTarget(options) {
+    if (options.target)
+        return options.target;
+    options.stdout?.error("Team command requires a story path or id.");
+    return undefined;
+}

package/dist/core/scaffold.js

@@ -2,6 +2,7 @@ import { markdown, text } from "./managed-files.js";
 import { agilePolicy, enterpriseSafetyPolicy, tddPolicy, workflowReview, workflowShape, workflowTddRun, } from "./policy.js";
 import { permissionPolicyFile } from "./permission-policy.js";
 import { storyTemplate, tddEvidenceTemplate } from "./templates.js";
+import { teamFiles } from "./team-scaffold.js";
 export function coreFiles() {
     return [
         {
@@ -48,6 +49,7 @@ adapters:
 }
 export function enterpriseFiles() {
     return [
+        ...teamFiles(),
         {
             path: ".speckit/flows/spec-flow.md",
             content: markdown(`# Spec Flow

package/dist/core/spec-score.d.ts

@@ -0,0 +1,16 @@
+export type ScoreCategory = {
+    name: string;
+    score: number;
+    passed: number;
+    total: number;
+    detail: string;
+};
+export type SpecScoreReport = {
+    score: number;
+    target?: string;
+    status: "excellent" | "healthy" | "needs-attention" | "blocked";
+    categories: ScoreCategory[];
+    blockers: string[];
+    recommendations: string[];
+};
+export declare function calculateSpecScore(root: string, target?: string): Promise<SpecScoreReport>;

package/dist/core/spec-score.js

@@ -0,0 +1,112 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { buildTeamReport } from "./team-report.js";
+import { validateWorkflowContract } from "./workflow-validator.js";
+export async function calculateSpecScore(root, target) {
+    const categories = target
+        ? await storyCategories(root, target)
+        : await projectCategories(root);
+    const score = Math.round(categories.reduce((sum, item) => sum + item.score, 0) / categories.length);
+    const blockers = categories
+        .filter((item) => item.score < 70)
+        .map((item) => `${item.name}: ${item.detail}`);
+    return {
+        score,
+        target,
+        status: statusFor(score, blockers.length),
+        categories,
+        blockers,
+        recommendations: recommendationsFor(categories, Boolean(target)),
+    };
+}
+async function projectCategories(root) {
+    const contract = await validateWorkflowContract(root);
+    return [
+        ratio("Workflow Contract", contract.filter((check) => check.ok).length, contract.length, "Core prompts, skills, adapters, and permissions"),
+        await fileScore(root, "Team Operating Model", [
+            ".speckit/team/roles.md",
+            ".speckit/team/artifact-ownership.md",
+            ".speckit/team/working-agreement.md",
+            ".speckit/team/review-gates.md",
+            ".speckit/team/handoff-protocol.md",
+        ]),
+        await fileScore(root, "Context And Session", [
+            ".speckit/memory/project-context.md",
+            ".speckit/sessions/active.md",
+            ".speckit/context/current.md",
+            ".speckit/context/subagent-handoff.md",
+        ]),
+        await fileScore(root, "Graph Sync", [
+            ".speckit/sync/beads-sync.jsonl",
+            ".beads/beads.jsonl",
+        ]),
+    ];
+}
+async function storyCategories(root, target) {
+    const team = await buildTeamReport(root, target);
+    if (!team.story) {
+        return [ratio("Story", 0, 1, team.blockers[0] ?? "Story not found")];
+    }
+    const allRoleChecks = team.roles.flatMap((role) => role.checks);
+    const qa = team.roles.find((role) => role.role === "QA/Test");
+    const developer = team.roles.find((role) => role.role === "Developer");
+    const reviewer = team.roles.find((role) => role.role === "Reviewer/Lead");
+    return [
+        ratio("Team Readiness", allRoleChecks.filter((check) => check.ok).length, allRoleChecks.length, "Role-owned story artifacts"),
+        ratio("Developer Trace", developer?.checks.filter((check) => check.ok).length ?? 0, developer?.checks.length ?? 1, "Dev Agent Record, File List, Change Log"),
+        ratio("TDD Evidence", qa?.checks.filter((check) => check.ok).length ?? 0, qa?.checks.length ?? 1, "Red, green, and refactor evidence"),
+        ratio("Review Gate", reviewer?.checks.filter((check) => check.ok).length ?? 0, reviewer?.checks.length ?? 1, "Review evidence and follow-ups"),
+    ];
+}
+async function fileScore(root, name, paths) {
+    const checks = await Promise.all(paths.map((path) => exists(root, path)));
+    const passed = checks.filter(Boolean).length;
+    return ratio(name, passed, paths.length, `${passed}/${paths.length} files present`);
+}
+function ratio(name, passed, total, detail) {
+    const denominator = Math.max(total, 1);
+    return {
+        name,
+        score: Math.round((passed / denominator) * 100),
+        passed,
+        total,
+        detail,
+    };
+}
+function statusFor(score, blockers) {
+    if (score >= 90 && blockers === 0)
+        return "excellent";
+    if (score >= 75)
+        return "healthy";
+    if (score >= 50)
+        return "needs-attention";
+    return "blocked";
+}
+function recommendationsFor(categories, storyMode) {
+    const weak = categories.filter((item) => item.score < 100);
+    if (weak.length === 0)
+        return ["Workflow is fully aligned."];
+    return weak.map((item) => {
+        if (storyMode && item.name === "TDD Evidence")
+            return "Complete red, green, and refactor evidence before review.";
+        if (storyMode && item.name === "Developer Trace")
+            return "Update Dev Agent Record, File List, and Change Log.";
+        if (storyMode && item.name === "Review Gate")
+            return "Record review outcome and follow-ups.";
+        if (item.name === "Context And Session")
+            return "Run memory refresh, session start, context, and compact before long work.";
+        if (item.name === "Graph Sync")
+            return "Run speckit sync and speckit graph setup.";
+        return `Fix ${item.name}.`;
+    });
+}
+async function exists(root, path) {
+    try {
+        await access(join(root, path));
+        const content = await readFile(join(root, path), "utf8");
+        return content.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/team-report.d.ts

@@ -0,0 +1,19 @@
+import { StoryResolution } from "./story.js";
+export type TeamCheck = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export type TeamRoleReport = {
+    role: string;
+    status: "ok" | "blocked" | "needs-attention" | "waiting";
+    checks: TeamCheck[];
+};
+export type TeamReport = {
+    status: "ok" | "blocked";
+    story?: Pick<StoryResolution, "id" | "path" | "title" | "status" | "evidencePath">;
+    roles: TeamRoleReport[];
+    blockers: string[];
+    warnings: string[];
+};
+export declare function buildTeamReport(root: string, target: string): Promise<TeamReport>;