@trieungoctam/speckit 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +18 -3
  2. package/docs/getting-started.md +131 -0
  3. package/docs/project-changelog.md +9 -0
  4. package/docs/release-checklist.md +1 -0
  5. package/docs/team-workflow.md +22 -0
  6. package/docs/use-cases.md +29 -9
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -10,11 +10,18 @@ The curated skill set is intentionally small: `spec-shape`, `spec-research`, `sp
10
10
 
11
11
  ## Quickstart
12
12
 
13
+ Recommended enterprise setup:
14
+
13
15
  ```bash
14
16
  npx @trieungoctam/speckit@latest setup
15
- npx @trieungoctam/speckit@latest init --ide cursor
16
- npx @trieungoctam/speckit@latest init --ide all
17
- npx @trieungoctam/speckit@latest init --enterprise --ide all
17
+ npx @trieungoctam/speckit@latest doctor --deep
18
+ npx @trieungoctam/speckit@latest validate
19
+ npx @trieungoctam/speckit@latest score
20
+ ```
21
+
22
+ One story end-to-end:
23
+
24
+ ```bash
18
25
  npx @trieungoctam/speckit@latest memory refresh
19
26
  npx @trieungoctam/speckit@latest session start "Add checkout validation"
20
27
  npx @trieungoctam/speckit@latest quick "Add checkout validation"
@@ -34,6 +41,13 @@ npx @trieungoctam/speckit@latest session checkpoint --note "red complete"
34
41
  npx @trieungoctam/speckit@latest review
35
42
  ```
36
43
 
44
+ Reset repo-local adapters before reinstalling:
45
+
46
+ ```bash
47
+ rm -rf .claude CLAUDE.md .codex AGENTS.md .cursor .opencode opencode.json
48
+ npx @trieungoctam/speckit@latest setup
49
+ ```
50
+
37
51
  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.
38
52
 
39
53
  Or install globally:
@@ -126,6 +140,7 @@ See `docs/adapters.md` for exact output paths.
126
140
 
127
141
  ## Guides
128
142
 
143
+ - `docs/getting-started.md` covers setup, adapter reset, verification, story execution, team audit, and close.
129
144
  - `docs/use-cases.md` covers setup, migration, quick changes, full planning, long sessions, TDD, graph automation, review, CI, and troubleshooting.
130
145
  - `docs/team-workflow.md` covers enterprise role ownership, status, audit, and handoff flow.
131
146
  - `docs/beads-viewer-setup.md` covers Beads Viewer installation, `bv` verification, and robot-safe graph usage.
package/docs/getting-started.md ADDED
@@ -0,0 +1,131 @@
1
+ # Getting Started
2
+
3
+ This guide is the shortest path to reset a repository, install Speckit, and run one enterprise Agile + TDD story.
4
+
5
+ ## 1. Install Or Reinstall Runtime Files
6
+
7
+ Interactive setup:
8
+
9
+ ```bash
10
+ npx @trieungoctam/speckit@latest setup
11
+ ```
12
+
13
+ Recommended answers for enterprise use:
14
+
15
+ ```text
16
+ Setup mode: Enterprise Agile + TDD harness
17
+ IDE adapter: All supported IDEs
18
+ Overwrite unmanaged files if needed: yes
19
+ Run Beads Viewer setup after init: yes
20
+ ```
21
+
22
+ Scripted setup:
23
+
24
+ ```bash
25
+ npx @trieungoctam/speckit@latest init --enterprise --ide all --force
26
+ npx @trieungoctam/speckit@latest graph setup
27
+ ```
28
+
29
+ Use one adapter when a repo standardizes on one IDE:
30
+
31
+ ```bash
32
+ npx @trieungoctam/speckit@latest init --enterprise --ide cursor --force
33
+ ```
34
+
35
+ Supported adapter names:
36
+
37
+ - `claude-code`
38
+ - `codex`
39
+ - `antigravity`
40
+ - `opencode`
41
+ - `cursor`
42
+ - `all`
43
+
44
+ ## 2. Verify The Install
45
+
46
+ ```bash
47
+ speckit doctor --deep
48
+ speckit validate
49
+ speckit score
50
+ ```
51
+
52
+ Expected behavior:
53
+
54
+ - `doctor --deep` checks generated files and external tools.
55
+ - `validate` checks prompt, skill, adapter, and workflow contract alignment.
56
+ - `score` may be below 100 before a session, context, and graph sync exist. That is normal.
57
+
58
+ ## 3. Start Work
59
+
60
+ ```bash
61
+ speckit memory refresh
62
+ speckit session start "Add customer export"
63
+ speckit quick "Add customer export"
64
+ ```
65
+
66
+ `quick` prints two paths:
67
+
68
+ - `.speckit/stories/<story>.md`
69
+ - `.speckit/evidence/<story>-tdd-evidence.md`
70
+
71
+ Use the printed story path in the next commands.
72
+
73
+ ## 4. Prepare Context And Graph
74
+
75
+ ```bash
76
+ speckit context .speckit/stories/<story>.md
77
+ speckit sync
78
+ speckit ready .speckit/stories/<story>.md
79
+ ```
80
+
81
+ If `ready` is blocked, fix the reported story, context, evidence, or graph issue before implementation.
82
+
83
+ ## 5. Implement With TDD
84
+
85
+ ```bash
86
+ speckit run .speckit/stories/<story>.md
87
+ ```
88
+
89
+ Then follow the red-green-refactor loop:
90
+
91
+ ```bash
92
+ npm test
93
+ speckit session checkpoint --note "red evidence captured"
94
+ npm test
95
+ speckit session checkpoint --note "green evidence captured"
96
+ speckit session checkpoint --note "refactor validated"
97
+ ```
98
+
99
+ Update the story and evidence file with command summaries, changed files, and completion notes.
100
+
101
+ ## 6. Team Review Flow
102
+
103
+ ```bash
104
+ speckit team status .speckit/stories/<story>.md
105
+ speckit team handoff .speckit/stories/<story>.md --from dev --to qa
106
+ speckit team audit .speckit/stories/<story>.md
107
+ speckit score .speckit/stories/<story>.md
108
+ ```
109
+
110
+ Use `team status` to see which role-owned artifact is missing. Use `team audit` before review or close.
111
+
112
+ ## 7. Review And Close
113
+
114
+ ```bash
115
+ speckit review
116
+ speckit session compact
117
+ speckit close .speckit/stories/<story>.md
118
+ speckit sync
119
+ speckit validate
120
+ ```
121
+
122
+ ## Resetting Adapters
123
+
124
+ To remove generated IDE adapter files before reinstalling Speckit in a repository:
125
+
126
+ ```bash
127
+ rm -rf .claude CLAUDE.md .codex AGENTS.md .cursor .opencode opencode.json
128
+ npx @trieungoctam/speckit@latest setup
129
+ ```
130
+
131
+ This removes repo-local adapter files only. Do not remove global IDE configuration unless you intentionally want to affect every project on the machine.
package/docs/project-changelog.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Project Changelog
2
2
 
3
+ ## 0.4.1 - 2026-05-11
4
+
5
+ ### Changed
6
+
7
+ - Added `docs/getting-started.md` with setup, adapter reset, verification, one-story execution, team audit, score, and close steps.
8
+ - Updated README, use-case, team workflow, and release checklist guidance for reinstalling repo-local adapters through Speckit.
9
+ - Updated prompt quality tests so adapter prompt coverage is validated from generators instead of requiring checked-out adapter files after local reset.
10
+
3
11
  ## 0.4.0 - 2026-05-11
4
12
 
5
13
  ### Added
@@ -14,6 +22,7 @@
14
22
 
15
23
  - 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.
16
24
  - `.beads/` is ignored as runtime graph mirror state.
25
+ - README and use-case guides now include adapter reset, reinstall, verification, story execution, score, team audit, and close steps.
17
26
 
18
27
  ### Quality
19
28
 
package/docs/release-checklist.md CHANGED
@@ -12,6 +12,7 @@ Before publishing Speckit:
12
12
  - [x] `npm pack --dry-run` includes only package-safe files.
13
13
  - [x] `package.json` name is `@trieungoctam/speckit` and `publishConfig.access` is `public`.
14
14
  - [x] README uses `npx @trieungoctam/speckit@latest`.
15
+ - [x] Getting started guide covers setup, adapter reset, verification, one story, team audit, score, and close.
15
16
  - [x] Adapter output paths match `docs/adapters.md`.
16
17
  - [x] Cursor output uses `.cursor/rules/*.mdc`, not `.cursorrules`.
17
18
  - [x] `speckit next` only invokes `bv --robot-*`.
package/docs/team-workflow.md CHANGED
@@ -15,8 +15,20 @@ Speckit Enterprise Team Workflow makes agentic development visible across roles.
15
15
 
16
16
  ## Flow
17
17
 
18
+ Start with enterprise setup and verification:
19
+
18
20
  ```bash
19
21
  speckit setup
22
+ speckit doctor --deep
23
+ speckit validate
24
+ speckit score
25
+ ```
26
+
27
+ Run one story:
28
+
29
+ ```bash
30
+ speckit memory refresh
31
+ speckit session start "Add customer export"
20
32
  speckit quick "Add customer export"
21
33
  speckit context .speckit/stories/<story>.md
22
34
  speckit sync
@@ -35,6 +47,16 @@ speckit score .speckit/stories/<story>.md
35
47
  - `speckit team handoff <story> --from <role> --to <role>` writes a durable handoff for long sessions or role transfer.
36
48
  - `speckit score <story>` gives a compact health score for team readiness, developer trace, TDD evidence, and review gate.
37
49
 
50
+ ## Role Handoff Examples
51
+
52
+ ```bash
53
+ speckit team handoff .speckit/stories/<story>.md --from product-owner --to analyst
54
+ speckit team handoff .speckit/stories/<story>.md --from analyst --to architect
55
+ speckit team handoff .speckit/stories/<story>.md --from architect --to dev
56
+ speckit team handoff .speckit/stories/<story>.md --from dev --to qa
57
+ speckit team handoff .speckit/stories/<story>.md --from qa --to reviewer
58
+ ```
59
+
38
60
  ## Enterprise Rule
39
61
 
40
62
  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 CHANGED
@@ -28,10 +28,29 @@ Best practices:
28
28
 
29
29
  - Prefer one IDE adapter per project at first. Add more adapters after the team agrees on the workflow.
30
30
  - Run `speckit validate` after init so broken prompts or missing skills are caught immediately.
31
+ - Run `speckit score` after init. A low score is normal until session, context, and graph sync artifacts exist.
31
32
  - Commit generated Speckit files so every teammate gets the same flow.
32
33
  - Keep `.speckit/` local to the repository. Avoid relying on global agent state for enterprise work.
33
34
 
34
- ## 2. Existing Project Migration
35
+ ## 2. Adapter Reset And Reinstall
36
+
37
+ Use when a repository already has old IDE adapter files and you want Speckit to regenerate them.
38
+
39
+ ```bash
40
+ rm -rf .claude CLAUDE.md .codex AGENTS.md .cursor .opencode opencode.json
41
+ npx @trieungoctam/speckit@latest setup
42
+ speckit doctor --deep
43
+ speckit validate
44
+ ```
45
+
46
+ Best practices:
47
+
48
+ - Reset only repo-local adapter files unless you intentionally want to affect global IDE behavior.
49
+ - Use `--ide all` for mixed teams; otherwise select the one IDE adapter the repo actually uses.
50
+ - Review generated adapter files before committing them.
51
+ - Keep `.speckit/` files. The reset command is for IDE adapters, not the Speckit workflow source of truth.
52
+
53
+ ## 3. Existing Project Migration
35
54
 
36
55
  Use when a project already has code, tests, and team conventions.
37
56
 
@@ -49,7 +68,7 @@ Best practices:
49
68
  - If an adapter prompt conflicts with local policy, update the adapter generator, not only the generated file.
50
69
  - Run project tests after migration even if Speckit only changed documentation and prompt files.
51
70
 
52
- ## 3. One Small Change
71
+ ## 4. One Small Change
53
72
 
54
73
  Use when the request is bounded and can fit into one story.
55
74
 
@@ -70,7 +89,7 @@ Best practices:
70
89
  - Keep acceptance criteria concrete enough to test.
71
90
  - Checkpoint after the red test, green test, refactor, and review boundary.
72
91
 
73
- ## 4. Full Feature Planning
92
+ ## 5. Full Feature Planning
74
93
 
75
94
  Use when the work includes multiple stories, architecture decisions, or team rollout.
76
95
 
@@ -91,7 +110,7 @@ Best practices:
91
110
  - Sync stories before graph commands so prioritization uses current metadata.
92
111
  - Use `sprint next` or `graph triage` to select work instead of choosing only by recency.
93
112
 
94
- ## 5. Long Agent Session
113
+ ## 6. Long Agent Session
95
114
 
96
115
  Use when work will span many tool calls, handoffs, or context compaction.
97
116
 
@@ -113,7 +132,7 @@ Best practices:
113
132
  - Use `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, or `NEEDS_CONTEXT` in handoffs.
114
133
  - Never pass a full conversation as handoff context. Pass files, acceptance criteria, constraints, and current status.
115
134
 
116
- ## 6. TDD Implementation
135
+ ## 7. TDD Implementation
117
136
 
118
137
  Use for all code stories.
119
138
 
@@ -135,7 +154,7 @@ Best practices:
135
154
  - Refactor only while tests stay green.
136
155
  - Put command output summaries in the evidence file. Avoid pasting large logs unless they are necessary.
137
156
 
138
- ## 7. Graph And Sprint Automation
157
+ ## 8. Graph And Sprint Automation
139
158
 
140
159
  Use when multiple stories exist and the next task is not obvious.
141
160
 
@@ -157,7 +176,7 @@ Best practices:
157
176
  - Treat graph output as prioritization input, not automatic permission to implement.
158
177
  - Re-run `sprint plan` when story status or dependencies change.
159
178
 
160
- ## 8. Review And Closure
179
+ ## 9. Review And Closure
161
180
 
162
181
  Use after implementation and tests pass.
163
182
 
@@ -183,7 +202,7 @@ Best practices:
183
202
  - Close only after the story has current evidence and a clean handoff.
184
203
  - Sync after closing so downstream graph and sprint views are current.
185
204
 
186
- ## 9. CI And Enterprise Rollout
205
+ ## 10. CI And Enterprise Rollout
187
206
 
188
207
  Use when Speckit becomes a shared team standard.
189
208
 
@@ -208,7 +227,7 @@ Best practices:
208
227
  - Add new workflow phases only through the central contract and tests.
209
228
  - Do not allow IDE-specific prompts to drift from the shared Speckit contract.
210
229
 
211
- ## 10. Troubleshooting
230
+ ## 11. Troubleshooting
212
231
 
213
232
  Use these checks when the workflow feels inconsistent.
214
233
 
@@ -216,6 +235,7 @@ Use these checks when the workflow feels inconsistent.
216
235
  speckit doctor --deep --json
217
236
  speckit validate --json
218
237
  speckit session status --json
238
+ speckit score --json
219
239
  speckit sync
220
240
  speckit graph triage --json
221
241
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trieungoctam/speckit",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "Enterprise Agile + TDD workflow compiler for agentic IDEs.",
5
5
  "type": "module",
6
6
  "files": [