@trieungoctam/speckit 0.3.6 → 0.4.0

package/README.md

@@ -23,6 +23,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
@@ -85,6 +89,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. |
@@ -118,6 +127,7 @@ See `docs/adapters.md` for exact output paths.
 ## Guides
 
 - `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>;

package/dist/core/team-report.js

@@ -0,0 +1,149 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { extractSection, resolveStory } from "./story.js";
+export async function buildTeamReport(root, target) {
+    const story = await resolveStory(root, target);
+    if (!story) {
+        return {
+            status: "blocked",
+            roles: [],
+            blockers: [`Story not found: ${target}`],
+            warnings: [],
+        };
+    }
+    const evidence = await readEvidence(root, story.evidencePath);
+    const roles = [
+        productOwner(story.content),
+        analyst(story.content),
+        architect(story.content),
+        developer(story.content),
+        await qa(story.evidencePath, evidence),
+        reviewer(evidence),
+    ];
+    const blockers = roles.flatMap((role) => role.checks.filter((check) => !check.ok).map((check) => `${role.role}: ${check.name} - ${check.detail}`));
+    return {
+        status: blockers.length ? "blocked" : "ok",
+        story: {
+            id: story.id,
+            path: story.path,
+            title: story.title,
+            status: story.status,
+            evidencePath: story.evidencePath,
+        },
+        roles,
+        blockers,
+        warnings: story.status === "ready-for-dev" ? [] : [`Story status is ${story.status ?? "missing"}`],
+    };
+}
+function productOwner(content) {
+    return role("Product Owner", [
+        check("business-goal", sectionHasDetail(content, "Business Goal") || sectionHasDetail(content, "Intent"), "Business goal or intent is filled"),
+        check("priority", sectionHasValue(content, "Business Goal", "Priority"), "Priority is recorded"),
+    ]);
+}
+function analyst(content) {
+    return role("Analyst", [
+        check("acceptance-criteria", hasActionableAcceptanceCriteria(content), "Acceptance criteria are testable"),
+        check("edge-cases", sectionHasDetail(content, "Edge Cases") || sectionHasValue(content, "Dev Notes", "Edge cases"), "Edge cases are recorded"),
+    ]);
+}
+function architect(content) {
+    return role("Architect", [
+        check("implementation-scope", sectionHasDetail(content, "Implementation Scope"), "Implementation scope is recorded"),
+        check("risk-notes", sectionHasDetail(content, "Architecture Notes") || sectionHasValue(content, "Notes", "Risks"), "Constraints or risks are recorded"),
+    ]);
+}
+function developer(content) {
+    return role("Developer", [
+        check("dev-agent-record", sectionHasDetail(content, "Dev Agent Record"), "Dev Agent Record exists"),
+        check("file-list", subsectionHasDetail(content, "File List"), "File List has at least one entry"),
+        check("change-log", sectionHasDetail(content, "Change Log"), "Change Log is updated"),
+    ]);
+}
+async function qa(evidencePath, evidence) {
+    return role("QA/Test", [
+        check("evidence-link", Boolean(evidencePath), evidencePath ?? "Missing linked evidence file"),
+        check("evidence-file", Boolean(evidence), evidencePath ?? "Missing linked evidence file"),
+        check("red-evidence", evidence ? sectionHasDetail(evidence, "Red") : false, "Red evidence is recorded"),
+        check("green-evidence", evidence ? sectionHasDetail(evidence, "Green") : false, "Green evidence is recorded"),
+        check("refactor-evidence", evidence ? sectionHasDetail(evidence, "Refactor") : false, "Refactor validation is recorded"),
+    ]);
+}
+function reviewer(evidence) {
+    const checks = [
+        check("review-evidence", evidence ? sectionHasDetail(evidence, "Review Evidence") : false, "Review outcome is recorded"),
+    ];
+    const report = role("Reviewer/Lead", checks);
+    return report.status === "blocked" ? { ...report, status: "waiting" } : report;
+}
+function role(roleName, checks) {
+    return {
+        role: roleName,
+        status: checks.every((item) => item.ok) ? "ok" : "blocked",
+        checks,
+    };
+}
+function check(name, ok, detail) {
+    return { name, ok, detail };
+}
+function hasActionableAcceptanceCriteria(content) {
+    const criteria = extractSection(content, "Acceptance Criteria");
+    if (!criteria)
+        return false;
+    return /Given .+|When .+|Then .+|AC\d+:/i.test(criteria) && !criteria.includes("...");
+}
+function sectionHasValue(content, heading, label) {
+    const section = extractSection(content, heading);
+    if (!section)
+        return false;
+    const pattern = new RegExp(`${escapeRegExp(label)}:\\s*\\S+`, "i");
+    return pattern.test(section);
+}
+function sectionHasDetail(content, heading) {
+    const section = extractSection(content, heading);
+    if (!section)
+        return false;
+    return hasDetail(section);
+}
+function subsectionHasDetail(content, heading) {
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => /^#{2,3}\s+/.test(line) && line.replace(/^#{2,3}\s+/, "").trim().toLowerCase() === heading.toLowerCase());
+    if (start === -1)
+        return false;
+    const collected = [];
+    for (const line of lines.slice(start + 1)) {
+        if (/^#{2,3}\s+/.test(line))
+            break;
+        collected.push(line);
+    }
+    return hasDetail(collected.join("\n"));
+}
+function hasDetail(section) {
+    return section
+        .split("\n")
+        .map((line) => line.replace(/^[-*\s]+/, "").trim())
+        .filter((line) => line && !line.startsWith("###"))
+        .some((line) => {
+        if (line.includes("..."))
+            return false;
+        if (/^[A-Za-z -]+:\s*$/.test(line))
+            return false;
+        if (/^(Command|Result|Reviewer|Outcome|Follow-ups):\s*$/i.test(line))
+            return false;
+        return true;
+    });
+}
+async function readEvidence(root, evidencePath) {
+    if (!evidencePath)
+        return undefined;
+    try {
+        await access(join(root, evidencePath));
+        return await readFile(join(root, evidencePath), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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

@@ -0,0 +1,2 @@
+import { ManagedFile } from "./managed-files.js";
+export declare function teamFiles(): ManagedFile[];

package/dist/core/team-scaffold.js

@@ -0,0 +1,92 @@
+import { markdown } from "./managed-files.js";
+export function teamFiles() {
+    return [
+        {
+            path: ".speckit/team/roles.md",
+            content: markdown(`# Spec Team Roles
+
+## Purpose
+
+Speckit maps team collaboration to owned artifacts. Roles do not imply separate people; one person can hold multiple roles, but every story must show which artifact is ready and which role is blocked.
+
+## Roles
+
+| Role | Owns | Exit Signal |
+| --- | --- | --- |
+| Product Owner | business goal, priority, scope intent | story has clear business value |
+| Analyst | acceptance criteria, edge cases, assumptions | story is testable |
+| Architect | implementation scope, constraints, risks | dev can start without guessing |
+| Developer | Dev Agent Record, File List, Change Log | implementation evidence is traceable |
+| QA/Test | red, green, refactor evidence | behavior is validated |
+| Reviewer/Lead | review evidence, approval, follow-ups | story can close |
+`),
+        },
+        {
+            path: ".speckit/team/artifact-ownership.md",
+            content: markdown(`# Spec Artifact Ownership
+
+## Story Artifacts
+
+- Product Owner owns \`Business Goal\`, \`Priority\`, and high-level intent.
+- Analyst owns \`Acceptance Criteria\`, \`Edge Cases\`, and assumptions.
+- Architect owns \`Implementation Scope\`, \`Architecture Notes\`, and risks.
+- Developer owns \`Dev Agent Record\`, \`File List\`, and \`Change Log\`.
+- QA/Test owns the linked TDD evidence file.
+- Reviewer/Lead owns review outcome and closure readiness.
+
+## Rule
+
+Do not move a story to the next gate by chat memory alone. Update the durable artifact first, then run \`speckit team status <story>\` or \`speckit team audit <story>\`.
+`),
+        },
+        {
+            path: ".speckit/team/working-agreement.md",
+            content: markdown(`# Spec Working Agreement
+
+## Agreements
+
+- One story is the unit of planning, implementation, review, and closure.
+- Every implementation story must have a linked TDD evidence file.
+- Agents and humans hand off through files, not conversation history.
+- Graph commands stay robot-safe through Speckit wrappers.
+- Review blocks closure when acceptance criteria, evidence, or file traceability are missing.
+`),
+        },
+        {
+            path: ".speckit/team/review-gates.md",
+            content: markdown(`# Spec Review Gates
+
+## Gates
+
+| Gate | Required Checks |
+| --- | --- |
+| shape | business goal, priority |
+| ready | acceptance criteria, scope, context, graph sync |
+| dev | Dev Agent Record, File List, Change Log |
+| qa | red, green, refactor evidence |
+| review | review outcome, follow-ups, unresolved risk |
+| close | sync, compact summary, docs impact |
+
+Run \`speckit team audit <story>\` before review and close.
+`),
+        },
+        {
+            path: ".speckit/team/handoff-protocol.md",
+            content: markdown(`# Spec Handoff Protocol
+
+## Handoff Contract
+
+Each handoff must include:
+
+- Story path and current status.
+- From role and to role.
+- Current blockers and warnings.
+- Files changed or expected files to inspect.
+- Test evidence state.
+- Next role checklist.
+
+Use \`speckit team handoff <story> --from <role> --to <role>\` to generate a durable handoff.
+`),
+        },
+    ];
+}

package/dist/core/templates.d.ts

@@ -1,2 +1,2 @@
-export declare const storyTemplate = "---\nstatus: draft\nevidence: .speckit/evidence/{{slug}}-tdd-evidence.md\ncontext: pending\nstory_key: {{slug}}\nac_count: 0\n---\n\n# Story: {{title}}\n\n## Intent\n{{intent}}\n\n## Acceptance Criteria\n- AC1: Given ...\n  When ...\n  Then ...\n\n## Implementation Scope\n- In scope:\n- Out of scope:\n- Files likely to read:\n- Files likely to modify:\n\n## Dev Notes\n- Existing patterns to reuse:\n- Architecture constraints:\n- Edge cases:\n- Previous-story learnings:\n\n## Tasks / Subtasks\n- [ ] Map acceptance criteria to tests.\n- [ ] RED: create or identify failing test.\n- [ ] GREEN: implement minimum passing change.\n- [ ] REFACTOR: improve design while tests stay green.\n- [ ] Update evidence, file list, and change log.\n\n## TDD Checklist\n- [ ] Test targets identified\n- [ ] Red evidence recorded\n- [ ] Green evidence recorded\n- [ ] Refactor validation recorded\n\n## Notes\n- Risks:\n- Dependencies:\n\n## Dev Agent Record\n### Test Intent\n\n### Debug Log\n\n### Completion Notes\n\n### File List\n\n## Change Log\n- {{date}}: Story drafted.\n\n## Spec Anti-Mistake Checklist\n- Reuse existing project patterns before adding new files.\n- Verify file locations before editing.\n- Do not introduce new libraries without explicit need.\n- Preserve existing behavior unless an acceptance criterion requires change.\n- Capture previous-story learnings if this continues prior work.\n- Do not mark any task complete without test or validation evidence.\n";
+export declare const storyTemplate = "---\nstatus: draft\nevidence: .speckit/evidence/{{slug}}-tdd-evidence.md\ncontext: pending\nstory_key: {{slug}}\nac_count: 0\n---\n\n# Story: {{title}}\n\n## Intent\n{{intent}}\n\n## Business Goal\n- Goal:\n- Priority: medium\n- Success signal:\n\n## Acceptance Criteria\n- AC1: Given ...\n  When ...\n  Then ...\n\n## Edge Cases\n- Boundary:\n- Error path:\n- State transition:\n\n## Implementation Scope\n- In scope:\n- Out of scope:\n- Files likely to read:\n- Files likely to modify:\n\n## Architecture Notes\n- Constraints:\n- Integration points:\n- Risks:\n\n## Dev Notes\n- Existing patterns to reuse:\n- Architecture constraints:\n- Edge cases:\n- Previous-story learnings:\n\n## Tasks / Subtasks\n- [ ] Map acceptance criteria to tests.\n- [ ] RED: create or identify failing test.\n- [ ] GREEN: implement minimum passing change.\n- [ ] REFACTOR: improve design while tests stay green.\n- [ ] Update evidence, file list, and change log.\n\n## TDD Checklist\n- [ ] Test targets identified\n- [ ] Red evidence recorded\n- [ ] Green evidence recorded\n- [ ] Refactor validation recorded\n\n## Notes\n- Risks:\n- Dependencies:\n\n## Dev Agent Record\n### Test Intent\n\n### Debug Log\n\n### Completion Notes\n\n### File List\n\n## Change Log\n- {{date}}: Story drafted.\n\n## Spec Anti-Mistake Checklist\n- Reuse existing project patterns before adding new files.\n- Verify file locations before editing.\n- Do not introduce new libraries without explicit need.\n- Preserve existing behavior unless an acceptance criterion requires change.\n- Capture previous-story learnings if this continues prior work.\n- Do not mark any task complete without test or validation evidence.\n";
 export declare const tddEvidenceTemplate = "---\nstatus: missing\nstory: {{story}}\nphase: not-started\n---\n\n# TDD Evidence: {{story}}\n\n## Test Intent\n- Acceptance criteria covered:\n- Test files:\n- Command:\n\n## Red\n- Command:\n- Result:\n- Failing reason:\n\n## Green\n- Command:\n- Result:\n- Passing evidence:\n\n## Refactor\n- Command:\n- Result:\n- Regression evidence:\n\n## Review Evidence\n- Reviewer:\n- Outcome:\n- Follow-ups:\n";

package/dist/core/templates.js

@@ -11,17 +11,32 @@ ac_count: 0
 ## Intent
 {{intent}}
 
+## Business Goal
+- Goal:
+- Priority: medium
+- Success signal:
+
 ## Acceptance Criteria
 - AC1: 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:
+
 ## Dev Notes
 - Existing patterns to reuse:
 - Architecture constraints:

package/docs/adapters.md

@@ -14,6 +14,18 @@ Speckit compiles one workflow into native files for five IDEs.
 
 Generated files include the `speckit:managed` marker. Speckit updates managed files idempotently and skips unmanaged files unless `--force` is provided.
 
+## Shared Enterprise Contract
+
+All adapters point agents back to the shared Speckit runtime:
+
+- `.speckit/agents/super-agent.md`
+- `.speckit/skills/catalog.md`
+- `.speckit/team/*.md`
+- `.speckit/context/current.md`
+- `.speckit/context/subagent-handoff.md`
+
+Adapters should not redefine team workflow rules independently. Update the shared generator and re-run `speckit init --enterprise --ide <name>` when the contract changes.
+
 ## Cursor Policy
 
 Cursor uses `.cursor/rules/*.mdc`. Speckit does not generate the legacy `.cursorrules` file.

package/docs/code-standards.md

@@ -5,5 +5,7 @@
 - Prefer deterministic file generation over runtime prompts.
 - Use `writeManagedFiles` for generated files so unmanaged user files are protected.
 - Keep adapter logic declarative: `name`, `displayName`, `outputPaths`, `render`.
+- Keep enterprise evaluators artifact-based. Team status, audit, and score should inspect durable files instead of chat history.
+- Keep public docs aligned with CLI help whenever a command is added.
 - Add tests for command behavior and adapter contracts before expanding implementation scope.
 - Do not invoke interactive external tools from automation paths.

package/docs/development-roadmap.md

@@ -4,9 +4,9 @@
 
 Speckit MVP is implemented and pushed to `git@github.com:trieungoctam/speckit.git` on `main`.
 
-Current package target: `@trieungoctam/speckit@0.3.5`.
+Current package target: `@trieungoctam/speckit@0.4.0`.
 
-The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, supports five IDE adapters, wraps Beads Viewer safely, includes an enterprise harness, and has automated prompt/readiness/session tests plus CI.
+The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, supports five IDE adapters, wraps Beads Viewer safely, includes an enterprise harness, and now exposes team-role workflow status, review-gate audit, handoff files, and runtime scoring.
 
 ## Milestones
 
@@ -20,17 +20,21 @@ The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, s
 | Beads integration | MVP Complete | `graph setup` prints install commands and prepares `.beads/beads.jsonl`; `next` and `graph triage/plan/insights` wrap BV robot mode; `sync` exports story metadata JSONL. |
 | Sprint automation | MVP Complete | `sprint plan` and `sprint next` select work from synced stories. |
 | Enterprise harness | MVP Complete | `init --enterprise` creates flow, tool-policy, and prompt harness files; `doctor --deep` verifies them. |
+| Enterprise team workflow | Complete | `init --enterprise` creates `.speckit/team/*`; `team status`, `team audit`, and `team handoff` expose role-owned artifacts and review blockers. |
+| Runtime scoring | Complete | `score` reports project or story workflow health across contract, team, session/context, graph, TDD, and review categories. |
 | Curated skill catalog | Complete | Speckit now generates focused phase skills, a schema, delegation statuses, and task hydration/sync-back guidance. |
 | Workflow contract validator | Complete | `speckit validate` and `doctor --deep` check phase order, core skills, router terms, run prompt terms, and adapter parity. |
 | Prompt architecture | Complete | Generated prompts now enforce artifact contracts, hard gates, common mistake prevention, TDD evidence, and review layers across adapters. |
 | Permission policy | MVP Complete | `.speckit/permissions.yaml` and `permissions audit` cover privacy files, heavy paths, destructive commands, and release commands. |
 | Validation | Complete | Build and `node:test` suite pass locally with flow contract gates. |
 | GitHub publish | Complete | Initial code pushed to `trieungoctam/speckit` at commit `7e5c582`; status docs follow-up in progress. |
-| npm package readiness | Ready | Package scoped as `@trieungoctam/speckit`; `npm pack --dry-run` passes. |
+| npm package readiness | Ready | Package scoped as `@trieungoctam/speckit`; `npm pack --dry-run` passes for `0.4.0`. |
 
 ## Next Roadmap
 
+- Add `score --threshold <n>` for CI gating after teams agree on rollout policy.
 - Add `review --deep` with multi-layer acceptance, edge-case, and production-readiness prompts.
 - Add graph drift and history correlation commands.
+- Add lockfile and drift detection for generated Speckit contracts.
 - Add GitHub trusted publishing for npm releases.
 - Add snapshot tests for full adapter file contents.

package/docs/enterprise-rollout.md

@@ -6,9 +6,10 @@ Speckit works best as a repo-local standard, then as an organization template.
 
 1. Pilot in one service repository with `speckit init --ide all`.
 2. Require stories to include acceptance criteria and TDD evidence.
-3. Add `speckit doctor` and project tests to CI.
-4. Export stories with `speckit sync` for task graph visibility.
-5. Roll the generated adapter pack into team templates.
+3. Require `speckit team status <story>` before implementation handoff.
+4. Add `speckit doctor`, `speckit validate`, `speckit score --json`, and project tests to CI.
+5. Export stories with `speckit sync` for task graph visibility.
+6. Roll the generated adapter pack into team templates.
 
 ## Governance Layers
 
@@ -16,12 +17,16 @@ Speckit works best as a repo-local standard, then as an organization template.
 | --- | --- | --- |
 | Company policy | Engineering leadership | `.speckit/rules/enterprise-safety.md` |
 | Team workflow | Tech lead | `.speckit/workflows/*.md` |
+| Team roles | Product / engineering lead | `.speckit/team/*.md` |
 | Repo standard | Maintainers | `AGENTS.md`, `CLAUDE.md`, IDE config |
 | Story evidence | Implementer | `.speckit/evidence/*.md` |
+| Review readiness | Reviewer / lead | `speckit team audit <story>` |
 
 ## Recommended Controls
 
 - Do not allow code stories to merge without red-green-refactor evidence.
 - Keep adapter output generated from Speckit instead of hand-maintaining per-IDE rules.
 - Treat `speckit doctor` warnings as rollout debt.
+- Treat `speckit score` as the adoption health metric. Start non-blocking, then define a threshold after the pilot.
+- Use `speckit team handoff` whenever work moves from development to QA or review.
 - Use Beads Viewer only through robot commands for non-interactive automation.

package/docs/product-contract.md

@@ -5,11 +5,13 @@ 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`, `validate`, `start`, `memory`, `permissions`, `session`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `sprint`, `graph`, `next`, `ready`, `run`, `review`, `close`.
+- The command surface: `init`, `doctor`, `validate`, `start`, `memory`, `permissions`, `session`, `team`, `score`, `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 enterprise team contract: Product Owner, Analyst, Architect, Developer, QA/Test, and Reviewer/Lead artifact ownership.
+- The runtime score contract: project and story health across workflow, team, session/context, graph, TDD, and review categories.
 - 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.
@@ -26,7 +28,24 @@ Speckit owns the workflow contract for enterprise Agile + TDD development with a
 ## State Model
 
 ```text
-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
+intake -> session -> memory-ready -> shaped -> planned -> sprint-ready -> context-ready -> synced -> graph-triaged -> team-status -> ready-for-dev -> tests-red -> checkpointed -> running -> tests-green -> refactor -> team-audit -> compacted -> review-ready -> closed
 ```
 
 Implementation starts only after `speckit ready <story>` passes. Review starts only after test evidence exists and the active session has a current checkpoint.
+
+## Team Artifact Model
+
+| Role | Owned Artifact |
+| --- | --- |
+| Product Owner | `Business Goal`, priority, success signal |
+| Analyst | `Acceptance Criteria`, `Edge Cases` |
+| Architect | `Implementation Scope`, `Architecture Notes` |
+| Developer | `Dev Agent Record`, `File List`, `Change Log` |
+| QA/Test | linked TDD evidence red, green, refactor sections |
+| Reviewer/Lead | `Review Evidence`, follow-ups, close readiness |
+
+`speckit team status` reports current ownership gaps. `speckit team audit` enforces the review gate. `speckit team handoff` records role transfer.
+
+## Runtime Score Model
+
+`speckit score` is a health signal, not a replacement for tests. It shows whether the project or story has enough durable workflow evidence to be understandable, reviewable, and handoff-ready.

package/docs/project-changelog.md

@@ -1,5 +1,24 @@
 # Project Changelog
 
+## 0.4.0 - 2026-05-11
+
+### Added
+
+- Added the Enterprise Team Workflow layer with generated team role, artifact ownership, working agreement, review gate, and handoff protocol files.
+- Added `speckit team status <story>` to show role-by-role artifact readiness for Product Owner, Analyst, Architect, Developer, QA/Test, and Reviewer/Lead.
+- Added `speckit team audit <story> [--json]` for review-gate blocking checks that can run in CI.
+- Added `speckit team handoff <story> --from <role> --to <role>` to create durable role handoff files.
+- Added `speckit score [story] [--json]` to score project or story workflow health for enterprise demos and CI health reporting.
+
+### Changed
+
+- Story templates and generated quick/plan stories now include business goal, priority, edge cases, implementation scope, architecture notes, Dev Agent Record, File List, and Change Log sections for team traceability.
+- `.beads/` is ignored as runtime graph mirror state.
+
+### Quality
+
+- Added enterprise team workflow tests for generated files, status, audit, and handoff behavior.
+
 ## 0.3.6 - 2026-05-11
 
 ### Added

package/docs/release-checklist.md

@@ -6,12 +6,16 @@ Before publishing Speckit:
 - [x] `npm run lint` passes.
 - [x] `npm test` passes.
 - [x] `bin/speckit init --ide all` works in a temporary directory.
+- [x] `speckit init --enterprise --ide all` creates `.speckit/team/*`.
+- [x] `speckit team status|audit|handoff` has test coverage.
+- [x] `speckit score [story] --json` has test coverage.
 - [x] `npm pack --dry-run` includes only package-safe files.
 - [x] `package.json` name is `@trieungoctam/speckit` and `publishConfig.access` is `public`.
 - [x] README uses `npx @trieungoctam/speckit@latest`.
 - [x] Adapter output paths match `docs/adapters.md`.
 - [x] Cursor output uses `.cursor/rules/*.mdc`, not `.cursorrules`.
 - [x] `speckit next` only invokes `bv --robot-*`.
+- [x] `.beads/` runtime mirror files are ignored by git.
 - [ ] License and attribution review is complete for Speckit, Speckit Method, and Beads Viewer inspiration.
 - [x] README quickstart is accurate.
 - [x] No secrets, local credentials, or generated private data are included.

package/docs/spec-quality-gates.md

@@ -29,6 +29,8 @@ Every phase must link to the next durable artifact.
 | context | story | context pack | story -> context |
 | sync | story | graph task | story -> task id |
 | run | task/story | TDD evidence | task -> evidence |
+| team status | story + evidence | role readiness | role -> artifact |
+| team audit | story + evidence | gate report | blocker -> owner |
 | review | diff + evidence | review checklist | evidence -> review |
 | close | review | changelog / graph close | review -> close |
 
@@ -51,6 +53,30 @@ All supported IDEs must receive the same Speckit policy:
 - Session/context instructions
 - Graph command safety
 
+## Team Gate
+
+Enterprise stories must expose role-owned artifacts:
+
+- Product Owner: business goal, priority, success signal.
+- Analyst: testable acceptance criteria and edge cases.
+- Architect: implementation scope, constraints, and risks.
+- Developer: Dev Agent Record, File List, and Change Log.
+- QA/Test: red, green, and refactor evidence.
+- Reviewer/Lead: review outcome and follow-ups.
+
+Run:
+
+```bash
+speckit team status <story>
+speckit team audit <story> --json
+```
+
+## Score Gate
+
+`speckit score` gives a project-level health signal across workflow contract, team operating model, context/session, and graph sync. `speckit score <story>` gives a story-level signal across team readiness, developer trace, TDD evidence, and review gate.
+
+Use score as a rollout metric first. Only turn it into a hard CI threshold after the team agrees on acceptable minimums.
+
 ## Release Gate
 
 Before release:
@@ -67,4 +93,5 @@ For enterprise releases:
 ```bash
 speckit init --enterprise --ide all
 speckit doctor --deep --json
+speckit score --json
 ```

package/docs/system-architecture.md

@@ -14,6 +14,9 @@ bin/speckit
 - `src/commands/*`: command implementations with filesystem-safe outputs.
 - `src/core/managed-files.ts`: creates or updates only Speckit-managed files unless forced.
 - `src/core/scaffold.ts`: defines core `.speckit/` rules, workflows, and templates.
+- `src/core/team-scaffold.ts`: defines generated team operating model files for enterprise mode.
+- `src/core/team-report.ts`: evaluates role-owned story artifacts for team status, audit, and handoff.
+- `src/core/spec-score.ts`: calculates project and story workflow health scores.
 - `src/core/test-detection.ts`: detects project test commands for TDD evidence.
 - `src/adapters/*`: renders native IDE config and instruction packs.
 - `src/adapters/tool-checks.ts`: reports external tool availability.
@@ -21,7 +24,22 @@ bin/speckit
 ## Data Flow
 
 ```text
-user intent -> CLI command -> markdown/json artifact -> IDE adapter -> agent workflow
+user intent -> CLI command -> markdown/json artifact -> team/status gates -> IDE adapter -> agent workflow
 ```
 
 The CLI does not depend on external workflow runtimes. Beads and Beads Viewer are optional integrations discovered at runtime.
+
+## Enterprise Team Layer
+
+```text
+story + evidence
+  -> team-report
+  -> team status / audit / handoff
+  -> score
+```
+
+Team checks are artifact-based. They inspect story sections, linked TDD evidence, and generated team contracts instead of relying on chat history.
+
+## Score Layer
+
+`speckit score` aggregates health across workflow contract, team operating model, context/session state, and graph sync. `speckit score <story>` aggregates story health across team readiness, developer trace, TDD evidence, and review gate.

package/docs/team-workflow.md

@@ -0,0 +1,40 @@
+# Enterprise Team Workflow
+
+Speckit Enterprise Team Workflow makes agentic development visible across roles. A role can be a person, a pair, or an agent, but every role owns durable artifacts.
+
+## Roles
+
+| Role | Owns | Speckit Checks |
+| --- | --- | --- |
+| Product Owner | business goal, priority | `Business Goal`, `Priority` |
+| Analyst | acceptance criteria, edge cases | `Acceptance Criteria`, `Edge Cases` |
+| Architect | scope, constraints, risk | `Implementation Scope`, `Architecture Notes` |
+| Developer | implementation trace | `Dev Agent Record`, `File List`, `Change Log` |
+| QA/Test | TDD proof | linked evidence `Red`, `Green`, `Refactor` |
+| Reviewer/Lead | approval | `Review Evidence` |
+
+## Flow
+
+```bash
+speckit setup
+speckit quick "Add customer export"
+speckit context .speckit/stories/<story>.md
+speckit sync
+speckit team status .speckit/stories/<story>.md
+speckit ready .speckit/stories/<story>.md
+speckit run .speckit/stories/<story>.md
+speckit team handoff .speckit/stories/<story>.md --from dev --to qa
+speckit team audit .speckit/stories/<story>.md
+speckit score .speckit/stories/<story>.md
+```
+
+## Status Vs Audit
+
+- `speckit team status <story>` answers where the story is blocked across roles.
+- `speckit team audit <story>` answers whether the story can pass the review gate.
+- `speckit team handoff <story> --from <role> --to <role>` writes a durable handoff for long sessions or role transfer.
+- `speckit score <story>` gives a compact health score for team readiness, developer trace, TDD evidence, and review gate.
+
+## Enterprise Rule
+
+Do not advance a story by chat memory alone. Update the story, evidence, session, or handoff artifact first, then run team status or audit.

package/docs/use-cases.md

@@ -162,6 +162,10 @@ Best practices:
 Use after implementation and tests pass.
 
 ```bash
+speckit team status .speckit/stories/<story>.md
+speckit team audit .speckit/stories/<story>.md
+speckit score .speckit/stories/<story>.md
+speckit team handoff .speckit/stories/<story>.md --from dev --to reviewer
 speckit review
 speckit session compact
 speckit close .speckit/stories/<story>.md
@@ -172,6 +176,9 @@ speckit validate
 Best practices:
 
 - Review acceptance coverage before style or preference issues.
+- Use `team status` to locate the role and artifact blocking review.
+- Use `score <story>` as a quick executive summary before review or demo.
+- Use `team handoff` when responsibility moves between dev, QA, reviewer, or lead.
 - 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.
@@ -187,12 +194,16 @@ npm run build
 npm test
 npx @trieungoctam/speckit@latest doctor --deep --json
 npx @trieungoctam/speckit@latest validate --json
+npx @trieungoctam/speckit@latest score --json
+npx @trieungoctam/speckit@latest team audit .speckit/stories/<story>.md --json
 ```
 
 Best practices:
 
 - Fail CI when `validate` returns `needs-attention`.
+- Use `score --json` as a non-blocking health metric until the team agrees on a threshold.
 - Require `doctor --deep` before release branches are merged.
+- Require `team audit` for stories that are ready for review or close.
 - 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.

package/docs/workflow-model.md

@@ -47,6 +47,26 @@ Outputs:
 - `.speckit/sprint/status.yaml`
 - `.speckit/sprint/plan.md`
 
+## Enterprise Team Lane
+
+Use when a story moves across product, analysis, architecture, development, QA, and review responsibilities.
+
+```bash
+speckit team status .speckit/stories/<story>.md
+speckit team handoff .speckit/stories/<story>.md --from dev --to qa
+speckit team audit .speckit/stories/<story>.md
+speckit score .speckit/stories/<story>.md
+```
+
+Outputs:
+
+- `.speckit/team/roles.md`
+- `.speckit/team/artifact-ownership.md`
+- `.speckit/team/review-gates.md`
+- `.speckit/team/handoffs/<handoff>.md`
+
+The team lane does not simulate people. It maps team responsibilities to durable artifacts so any person or agent can see which role is blocking the story.
+
 ## TDD Evidence Gate
 
 Each code story must record:
@@ -72,3 +92,14 @@ Long-running agent work must keep durable state outside chat history:
 `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.
 
 Run `speckit graph setup` on a new machine to print Beads Viewer install commands, check `br`/`bd`/`bv`, and prepare `.beads/beads.jsonl`.
+
+## Runtime Score
+
+Use score as the compact executive summary of workflow health:
+
+```bash
+speckit score
+speckit score .speckit/stories/<story>.md
+```
+
+Project score checks workflow contract, team operating model, context/session, and graph sync. Story score checks team readiness, developer trace, TDD evidence, and review gate.

package/package.json

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