@trieungoctam/speckit 0.3.6 → 0.4.1

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,62 @@
+# 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
+
+Start with enterprise setup and verification:
+
+```bash
+speckit setup
+speckit doctor --deep
+speckit validate
+speckit score
+```
+
+Run one story:
+
+```bash
+speckit memory refresh
+speckit session start "Add customer export"
+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.
+
+## Role Handoff Examples
+
+```bash
+speckit team handoff .speckit/stories/<story>.md --from product-owner --to analyst
+speckit team handoff .speckit/stories/<story>.md --from analyst --to architect
+speckit team handoff .speckit/stories/<story>.md --from architect --to dev
+speckit team handoff .speckit/stories/<story>.md --from dev --to qa
+speckit team handoff .speckit/stories/<story>.md --from qa --to reviewer
+```
+
+## 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

@@ -28,10 +28,29 @@ 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.
+- Run `speckit score` after init. A low score is normal until session, context, and graph sync artifacts exist.
 - 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
+## 2. Adapter Reset And Reinstall
+
+Use when a repository already has old IDE adapter files and you want Speckit to regenerate them.
+
+```bash
+rm -rf .claude CLAUDE.md .codex AGENTS.md .cursor .opencode opencode.json
+npx @trieungoctam/speckit@latest setup
+speckit doctor --deep
+speckit validate
+```
+
+Best practices:
+
+- Reset only repo-local adapter files unless you intentionally want to affect global IDE behavior.
+- Use `--ide all` for mixed teams; otherwise select the one IDE adapter the repo actually uses.
+- Review generated adapter files before committing them.
+- Keep `.speckit/` files. The reset command is for IDE adapters, not the Speckit workflow source of truth.
+
+## 3. Existing Project Migration
 
 Use when a project already has code, tests, and team conventions.
 
@@ -49,7 +68,7 @@ Best practices:
 - 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
+## 4. One Small Change
 
 Use when the request is bounded and can fit into one story.
 
@@ -70,7 +89,7 @@ Best practices:
 - Keep acceptance criteria concrete enough to test.
 - Checkpoint after the red test, green test, refactor, and review boundary.
 
-## 4. Full Feature Planning
+## 5. Full Feature Planning
 
 Use when the work includes multiple stories, architecture decisions, or team rollout.
 
@@ -91,7 +110,7 @@ Best practices:
 - 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
+## 6. Long Agent Session
 
 Use when work will span many tool calls, handoffs, or context compaction.
 
@@ -113,7 +132,7 @@ Best practices:
 - 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
+## 7. TDD Implementation
 
 Use for all code stories.
 
@@ -135,7 +154,7 @@ Best practices:
 - 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
+## 8. Graph And Sprint Automation
 
 Use when multiple stories exist and the next task is not obvious.
 
@@ -157,11 +176,15 @@ Best practices:
 - 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
+## 9. Review And Closure
 
 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,11 +195,14 @@ 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.
 
-## 9. CI And Enterprise Rollout
+## 10. CI And Enterprise Rollout
 
 Use when Speckit becomes a shared team standard.
 
@@ -187,17 +213,21 @@ 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.
 
-## 10. Troubleshooting
+## 11. Troubleshooting
 
 Use these checks when the workflow feels inconsistent.
 
@@ -205,6 +235,7 @@ Use these checks when the workflow feels inconsistent.
 speckit doctor --deep --json
 speckit validate --json
 speckit session status --json
+speckit score --json
 speckit sync
 speckit graph triage --json
 ```

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.1",
   "description": "Enterprise Agile + TDD workflow compiler for agentic IDEs.",
   "type": "module",
   "files": [