bmad-module-ultracode-goal 2.3.0 → 3.0.0
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.
- package/.claude-plugin/marketplace.json +1 -1
- package/README.md +3 -3
- package/docs/_internal/STABILITY.md +17 -8
- package/docs/architecture.md +14 -8
- package/docs/comparison.md +20 -20
- package/docs/cross-session-recall.md +136 -54
- package/docs/getting-started.md +23 -13
- package/docs/how-it-works.md +4 -4
- package/docs/index.md +1 -1
- package/docs/knowledge-graph-refresh.md +31 -13
- package/docs/operating-tips.md +4 -12
- package/docs/troubleshooting.md +2 -1
- package/docs/why-ultracode-goal.md +3 -3
- package/package.json +18 -7
- package/skills/ucg-create-story/LICENSE.md +47 -0
- package/skills/ucg-create-story/SKILL.md +438 -0
- package/skills/ucg-create-story/checklist.md +357 -0
- package/skills/ucg-create-story/customize.toml +40 -0
- package/skills/ucg-create-story/discover-inputs.md +88 -0
- package/skills/ucg-create-story/template.md +49 -0
- package/skills/ucg-dev-story/LICENSE.md +49 -0
- package/skills/ucg-dev-story/SKILL.md +561 -0
- package/skills/ucg-dev-story/checklist.md +82 -0
- package/skills/ucg-dev-story/customize.toml +40 -0
- package/skills/ucg-formalize/SKILL.md +118 -46
- package/skills/ucg-resolve/SKILL.md +4 -2
- package/skills/ucg-status/SKILL.md +1 -1
- package/skills/ultracode-goal/SKILL.md +7 -5
- package/skills/ultracode-goal/assets/ucg-awareness/bmad-testarch-test-design.toml +1 -1
- package/skills/ultracode-goal/assets/ucg-awareness/{bmad-create-story.toml → ucg-create-story.toml} +10 -9
- package/skills/ultracode-goal/customize.toml +20 -6
- package/skills/ultracode-goal/references/define-done.md +15 -7
- package/skills/ultracode-goal/references/execute.md +26 -9
- package/skills/ultracode-goal/references/finalize.md +32 -25
- package/skills/ultracode-goal/references/gate.md +5 -3
- package/skills/ultracode-goal/references/health-check.md +4 -2
- package/skills/ultracode-goal/references/ingest-and-scope.md +29 -26
- package/skills/ultracode-goal/references/preflight.md +78 -30
- package/skills/ultracode-goal/scripts/claim_check.py +374 -0
- package/skills/ultracode-goal/scripts/drive_epic.py +1 -1
- package/skills/ultracode-goal/scripts/formalize_check.py +409 -72
- package/skills/ultracode-goal/scripts/gate_eval.py +203 -6
- package/skills/ultracode-goal/scripts/headless_envelope.py +30 -14
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +1762 -123
- package/skills/ultracode-goal/scripts/lib/mem_common.py +1277 -23
- package/skills/ultracode-goal/scripts/link_worktree_deps.py +174 -0
- package/skills/ultracode-goal/scripts/mem_observation.py +500 -147
- package/skills/ultracode-goal/scripts/mem_recall.py +307 -372
- package/skills/ultracode-goal/scripts/merge_customization.py +54 -27
- package/skills/ultracode-goal/scripts/mutate_check.py +200 -26
- package/skills/ultracode-goal/scripts/preflight_check.py +251 -103
- package/skills/ultracode-goal/scripts/red_ids.py +11 -1
- package/skills/ultracode-goal/scripts/story_sizing.py +107 -1
- package/tools/cli/commands/status.js +92 -47
- package/tools/cli/lib/ide-skills.js +5 -1
- package/tools/cli/lib/installer.js +12 -8
- package/.gitattributes +0 -16
- package/.nvmrc +0 -1
- package/docs/_internal/RELEASING.md +0 -134
- package/tools/build-docs.js +0 -350
- package/tools/validate-docs-links.js +0 -936
- package/tools/validate-fixtures.js +0 -161
- package/website/README.md +0 -92
- package/website/astro.config.mjs +0 -150
- package/website/package-lock.json +0 -8454
- package/website/package.json +0 -26
- package/website/public/favicon.svg +0 -13
- package/website/public/img/ucg-logo.svg +0 -73
- package/website/public/js/mermaid-lightbox.js +0 -67
- package/website/public/robots.txt +0 -36
- package/website/src/components/Banner.astro +0 -82
- package/website/src/components/Header.astro +0 -146
- package/website/src/components/MobileMenuFooter.astro +0 -69
- package/website/src/content/config.ts +0 -6
- package/website/src/lib/site-url.js +0 -28
- package/website/src/pages/404.astro +0 -11
- package/website/src/rehype-base-paths.js +0 -83
- package/website/src/rehype-markdown-links.js +0 -189
- package/website/src/styles/custom.css +0 -674
- package/website/tsconfig.json +0 -9
package/docs/troubleshooting.md
CHANGED
|
@@ -41,7 +41,8 @@ flowchart TD
|
|
|
41
41
|
- **Claude Code below the minimum versions.** The primitive-version blocker is marked non-remediable: the script can't upgrade the host. Update Claude Code.
|
|
42
42
|
- **A repository with nothing committed.** On a fresh `git init` (or an orphan branch) the `git_unborn` blocker is non-remediable: the run never makes the commit its Epic branch would start from, because that commit would sit outside its only rollback, the Epic branch. Commit a baseline yourself (the BMAD install, the planning artifacts and the project skeleton) on your base branch, a protected branch such as `main` and never an Epic branch, then re-run. If HEAD already names an Epic branch, the blocker's detail gives the command that points it at the base first.
|
|
43
43
|
- **A refused settings write.** Preflight writes its hooks and allow rules into `.claude/settings.local.json`, which Claude Code treats as protected. Under Auto Mode the permission classifier may refuse that write, or let it land and refuse the next calls, as self-modification. The run then stops rather than work around the refusal, and the decision log names the write. Attended, approve it under `/permissions` (on its Recently denied tab) or apply it yourself; the run re-checks the hooks and continues. Headless, there is nobody to approve it, and `/ucg-resolve` is not the way back: take the Epic through preflight attended (see [hook security](./getting-started.md#hook-security)).
|
|
44
|
-
- **
|
|
44
|
+
- **Story skills not installed.** The run delegates story creation to `ucg-create-story` and implementation to `ucg-dev-story`, the story skills UCG ships in place of BMAD Method's deprecated `bmad-create-story` and `bmad-dev-story`. UCG's installer copies them beside the `ultracode-goal` skill, so a missing one means a partial or older UCG install, or an install from the plugin marketplace alone, which ships only the `ultracode-goal` skill. The `story_skills` blocker is non-remediable: the run neither installs them nor works around them. Its detail names the fix, `npx bmad-module-ultracode-goal update` from the project root (`install` where UCG was never installed there). BMAD's own shims, installed with `--shims`, do not satisfy it (see [Prerequisites](./getting-started.md#prerequisites)). The same check runs on every resume, so a story skill deleted mid-Epic, by hand or by an install interrupted while it re-copies the UCG skills, stops the next spawn instead of letting it improvise.
|
|
45
|
+
- **TEA skills not installed.** The run delegates test design, acceptance tests, review and the gate to TEA's `bmad-testarch-*` skills. Production needs all eight. `--light` needs three: `bmad-testarch-framework`, `bmad-testarch-test-design` and `bmad-testarch-trace`. The `tea_skills` blocker is non-remediable: the run never installs TEA. UCG supports BMAD 6 with TEA 1.27.x, which BMAD Method 6.12.2 and later install. Add or repair TEA from the project root with `npx bmad-method install`, with the `tea` module selected, then re-run. If the detail says it found `bmad-tea-*` skills instead, the project has TEA 3.0 or later, which renamed the skills UCG calls. UCG does not support it yet: install TEA 1.27.x through BMAD 6 instead (see [Prerequisites](./getting-started.md#prerequisites)). Preflight checks skill names, not the TEA version. TEA 2.x moved to BMAD 7's module format but kept the `bmad-testarch-*` names, so preflight does not catch it, though UCG does not support it either. Preflight checks these skills at launch only. A TEA skill removed mid-Epic escalates the story that calls it.
|
|
45
46
|
|
|
46
47
|
The decision log carries the full blocker list with what each needs to clear. Read it, clear the items, re-run.
|
|
47
48
|
|
|
@@ -11,7 +11,7 @@ Three intuitive shortcuts all push an unattended Epic toward false completion, a
|
|
|
11
11
|
|
|
12
12
|
**The evaluator only sees the transcript.** Claude Code's `/goal` mode drives a loop until a success condition is met, then asks an evaluator to confirm. But that evaluator reads the transcript; it cannot open a file on disk. It cannot read TEA's `gate-decision.json`. So if you let the `/goal` condition be the final word on "is this story done," you have asked the model to grade its own homework from its own notes. The model cannot be the judge of its own completion: the thing that decides "done" has to be something it cannot author.
|
|
13
13
|
|
|
14
|
-
**`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one implementation commit per green story plus its gate's evidence commit. See the [gate model](./gate-model.md) and [architecture](./architecture.md) for how this is wired.
|
|
14
|
+
**`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one implementation commit per green story plus its gate's evidence commit. On a project that gitignores its BMAD output, that undo covers the code only: what the run wrote under the ignored tree stays, the story files, the run's decision log and its sprint-status edits among it. See the [gate model](./gate-model.md) and [architecture](./architecture.md) for how this is wired.
|
|
15
15
|
|
|
16
16
|
**Memory is context, not enforcement.** It is tempting to encode the run's invariants ("never commit on `main`", "never commit before tests pass") into Auto Memory or a CLAUDE.md rule and trust the model to honor them. But memory is context the model may or may not weigh; it does not *block* a `git commit`. An invariant that lives only in memory is a suggestion. An invariant that must hold has to live somewhere the model cannot talk its way past.
|
|
17
17
|
|
|
@@ -21,7 +21,7 @@ UltraCode Goal answers each shortcut with a layer the model cannot override, exc
|
|
|
21
21
|
|
|
22
22
|
**1. Deterministic gate truth.** Completion is decided by `scripts/gate_eval.py`, which reads TEA's `gate-decision.json` and maps its gate status to a routing verdict: `PASS`/`WAIVED` advance, `CONCERNS` defers, `FAIL` re-loops, `NOT_EVALUATED` escalates. The script never re-derives TEA's thresholds and never consults the transcript; it reads the artifact as given. The model produces evidence; the script reads the verdict. They are different things on purpose. See the [gate model](./gate-model.md).
|
|
23
23
|
|
|
24
|
-
**2. Hooks as invariants.** The invariants that must hold (no commit on a protected branch, no commit before a story's tests have actually run green, and
|
|
24
|
+
**2. Hooks as invariants.** The invariants that must hold (no commit on a protected branch, no commit before a story's tests have actually run green, and five more covering marker freshness, an empty staged index, un-skipped acceptance tests, and two for Cross-Session Recall) live in a **PreToolUse** hook, not in memory. The hook inspects each `git commit`/`git push`, and every other tool call while a run latch is present, and denies the call when any of them is violated. It is merged into `.claude/settings.local.json` at preflight and asserted active before the run goes unattended. A denied commit is enforcement; a remembered rule is not. See [architecture](./architecture.md).
|
|
25
25
|
|
|
26
26
|
**3. Budget enforcement.** This is the one layer that rests on the conductor following a rule. A **Stop** hook tracks turns against `max_turns_per_story` and writes an escalation marker when it is breached, but it never blocks, and it counts once per response, so re-loops inside one response do not move it. The conductor reads that count before each story and each re-loop, and the gate's re-loop budget turns a `reloop` that would exceed it into an `escalate`. A story that passes its gate after an overrun is not escalated: the gate decides completion, and the overrun is logged as a sizing note. A `/goal` condition's literal "…or stop after N turns" clause binds only when an operator starts a `/goal` (the conductor cannot start one itself), and for `drive_epic.py` spawns a `--session-timeout` wall clock is the backstop. See [how it works](./how-it-works.md).
|
|
27
27
|
|
|
@@ -34,4 +34,4 @@ UltraCode Goal is narrow on purpose. It is the wrong tool when:
|
|
|
34
34
|
- **There is no BMAD project.** It needs `_bmad/` config, a `sprint-status.yaml`, or an Epic to target. With none of the three present, Stage 1 hard-stops and points you at `bmad-bmb-setup` and `bmad-sprint-planning`. See [getting started](./getting-started.md).
|
|
35
35
|
- **There are no Epics or stories.** The unit of delivery is one Epic with acceptance-bearing stories. There is nothing for the gate to read against a loose task list.
|
|
36
36
|
- **The work is exploratory.** If the Definition-of-Done is genuinely undecided (open product or architecture questions, "TBD" on a load-bearing requirement), preflight refuses to launch rather than let an unattended run guess. That refusal is correct; resolve the decisions first, then run.
|
|
37
|
-
- **You want interactive pairing.** The whole point is that the human leaves the loop after preflight. If you want to review each step, drive the underlying BMAD skills (`bmad-
|
|
37
|
+
- **You want interactive pairing.** The whole point is that the human leaves the loop after preflight. If you want to review each step, drive the underlying BMAD skills (`bmad-build`, `bmad-code-review`, the TEA workflows) directly instead.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "bmad-module-ultracode-goal",
|
|
4
|
-
"version": "
|
|
4
|
+
"version": "3.0.0",
|
|
5
5
|
"description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"bmad",
|
|
@@ -32,6 +32,8 @@
|
|
|
32
32
|
"bmad-module-ultracode-goal": "tools/ucg-npx-wrapper.js"
|
|
33
33
|
},
|
|
34
34
|
"scripts": {
|
|
35
|
+
"changes:pr": "node tools/changes.js pr",
|
|
36
|
+
"changes:preview": "node tools/changes.js preview",
|
|
35
37
|
"docs:build": "node tools/build-docs.js",
|
|
36
38
|
"docs:dev": "npm run --prefix website docs:dev",
|
|
37
39
|
"docs:preview": "npm run --prefix website preview",
|
|
@@ -40,26 +42,35 @@
|
|
|
40
42
|
"lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
|
|
41
43
|
"lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
|
|
42
44
|
"lint:instructions": "uvx lintlang@0.8.1 scan skills --exclude \"**/scripts/tests/fixtures/**\" --fail-on fail",
|
|
43
|
-
"lint:md": "markdownlint-cli2 \"**/*.md\"",
|
|
45
|
+
"lint:md": "markdownlint-cli2 \"**/*.md\" && node tools/changes.js lint",
|
|
44
46
|
"prepare": "husky || exit 0",
|
|
45
47
|
"postprepare": "node tools/link-reference-skills.js --quiet || exit 0",
|
|
46
|
-
"quality": "run-p --print-label --aggregate-output format:check lint lint:md lint:instructions test:install test:cli test:python test:rehype test:docs-links-tool test:skill-links validate:skills validate:refs validate:fixtures validate:docs-links",
|
|
48
|
+
"quality": "run-p --print-label --aggregate-output format:check lint lint:md lint:instructions test:install test:cli test:pack test:python test:rehype test:docs-links-tool test:skill-links test:em-dash-tool test:tool-requirements-tool test:context-index-tool test:changes-tool validate:skills validate:refs validate:fixtures validate:docs-links validate:em-dash validate:tool-requirements validate:context-index validate:changes",
|
|
47
49
|
"skills:link": "node tools/link-reference-skills.js",
|
|
48
50
|
"test": "npm run quality",
|
|
51
|
+
"test:changes-tool": "node test/test-changes.js && node test/test-covered-surfaces.js && node test/test-release-state.js",
|
|
49
52
|
"test:cli": "node test/test-cli-integration.js",
|
|
50
|
-
"test:
|
|
53
|
+
"test:context-index-tool": "node test/test-validate-context-index.js",
|
|
54
|
+
"test:docs-links-tool": "node test/test-validate-docs-links.js && node test/test-check-required-checks.js && node tools/check-required-checks.js --releasing",
|
|
55
|
+
"test:em-dash-tool": "node test/test-validate-no-em-dash.js",
|
|
51
56
|
"test:install": "node test/test-installation-components.js",
|
|
52
|
-
"test:
|
|
57
|
+
"test:pack": "node test/test-pack-contents.js",
|
|
58
|
+
"test:python": "uv run --with pytest==9.1.1 --with pytest-xdist==3.8.0 --with pyyaml==6.0.3 pytest skills/ultracode-goal/scripts/tests/ test/ -o \"python_files=test-*.py test_*.py *_test.py\" -n auto",
|
|
53
59
|
"test:rehype": "node test/test-rehype-markdown-links.js",
|
|
54
60
|
"test:skill-links": "node test/test-link-reference-skills.js",
|
|
61
|
+
"test:tool-requirements-tool": "node test/test-tool-requirements.js",
|
|
55
62
|
"ucg:install": "node tools/cli/ucg-cli.js install",
|
|
56
63
|
"ucg:status": "node tools/cli/ucg-cli.js status",
|
|
57
64
|
"ucg:uninstall": "node tools/cli/ucg-cli.js uninstall",
|
|
58
65
|
"ucg:update": "node tools/cli/ucg-cli.js update",
|
|
66
|
+
"validate:changes": "node tools/changes.js check",
|
|
67
|
+
"validate:context-index": "node tools/validate-context-index.js",
|
|
59
68
|
"validate:docs-links": "node tools/validate-docs-links.js --strict",
|
|
69
|
+
"validate:em-dash": "node tools/validate-no-em-dash.js --strict",
|
|
60
70
|
"validate:fixtures": "node tools/validate-fixtures.js --strict",
|
|
61
71
|
"validate:refs": "node tools/validate-file-refs.js --strict",
|
|
62
|
-
"validate:skills": "node tools/validate-skills.js --strict"
|
|
72
|
+
"validate:skills": "node tools/validate-skills.js --strict",
|
|
73
|
+
"validate:tool-requirements": "node tools/tool-requirements.js --check"
|
|
63
74
|
},
|
|
64
75
|
"lint-staged": {
|
|
65
76
|
"*.{js,cjs,mjs}": [
|
|
@@ -87,7 +98,6 @@
|
|
|
87
98
|
},
|
|
88
99
|
"devDependencies": {
|
|
89
100
|
"@eslint/js": "^9.33.0",
|
|
90
|
-
"conventional-changelog-cli": "^5.0.0",
|
|
91
101
|
"csv-parse": "^6.1.0",
|
|
92
102
|
"eslint": "^9.33.0",
|
|
93
103
|
"eslint-config-prettier": "^10.1.8",
|
|
@@ -100,6 +110,7 @@
|
|
|
100
110
|
"npm-run-all2": "^8.0.4",
|
|
101
111
|
"prettier": "^3.7.4",
|
|
102
112
|
"prettier-plugin-packagejson": "^2.5.19",
|
|
113
|
+
"semver": "^7.8.5",
|
|
103
114
|
"unist-util-visit": "5.1.0",
|
|
104
115
|
"yaml": "^2.7.0",
|
|
105
116
|
"yaml-eslint-parser": "^1.2.3"
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# License
|
|
2
|
+
|
|
3
|
+
This skill is adapted from the `bmad-create-story` workflow of BMAD Method 6.12.4
|
|
4
|
+
(<https://github.com/bmad-code-org/BMAD-METHOD>, `src/bmm-skills/v6-shims/bmad-create-story`), which BMAD
|
|
5
|
+
deprecated in favour of `bmad-build` and removes at v7. UltraCode Goal ships this copy under its
|
|
6
|
+
own name so its runs keep the story-file contract without the deprecated shim installed.
|
|
7
|
+
|
|
8
|
+
The changes from upstream are limited to: the skill name and description, with the shim lifecycle
|
|
9
|
+
metadata removed; this attribution and the notice below; a fallback for loading config when
|
|
10
|
+
`_bmad/scripts/resolve_config.py` is absent; the customization resolver called without
|
|
11
|
+
`--project-root`, which BMAD Method 6.10's resolver does not accept, with a fallback for
|
|
12
|
+
`on_complete` when the call fails; every call to a BMAD resolver run with `uv run --no-project`,
|
|
13
|
+
so that in a Python project uv never sets up the project's own environment (a `.venv` and a
|
|
14
|
+
`uv.lock`) for a resolver with no script header (BMAD Method 6.10's have none); the removed
|
|
15
|
+
deprecation notice; references to the dev-story workflow renamed to `ucg-dev-story`, and the
|
|
16
|
+
template's note about the nonexistent `validate-create-story` replaced by a check against this
|
|
17
|
+
skill's checklist; the checklist's pointers to a `workflow.md` the skill does not ship replaced by
|
|
18
|
+
its `SKILL.md`; and em dashes replaced by other punctuation. The workflow steps are otherwise
|
|
19
|
+
unchanged.
|
|
20
|
+
|
|
21
|
+
UltraCode Goal's own changes are under its license (the `LICENSE` file at the repository root).
|
|
22
|
+
The upstream work is distributed under the following license:
|
|
23
|
+
|
|
24
|
+
MIT License
|
|
25
|
+
|
|
26
|
+
Copyright (c) 2025 BMad Code, LLC
|
|
27
|
+
|
|
28
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
29
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
30
|
+
in the Software without restriction, including without limitation the rights
|
|
31
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
32
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
33
|
+
furnished to do so, subject to the following conditions:
|
|
34
|
+
|
|
35
|
+
The above copyright notice and this permission notice shall be included in all
|
|
36
|
+
copies or substantial portions of the Software.
|
|
37
|
+
|
|
38
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
39
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
40
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
41
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
42
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
43
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
44
|
+
SOFTWARE.
|
|
45
|
+
|
|
46
|
+
BMad, BMad Method and BMad Core are trademarks of BMad Code, LLC. Their use here does not
|
|
47
|
+
grant any rights to use the trademarks for any other purpose.
|
|
@@ -0,0 +1,438 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ucg-create-story
|
|
3
|
+
description: "Creates the story file an UltraCode Goal run gates and implements: `{story_key}.md` with numbered acceptance criteria, adapted from BMAD Method's create-story workflow so a run needs no deprecated BMAD shim. Use when an UltraCode Goal skill (ultracode-goal or ucg-formalize) delegates story creation to it, or when invoked by name; not a general story-creation entry point."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- Adapted for UltraCode Goal from BMAD Method 6.12.4, src/bmm-skills/v6-shims/bmad-create-story. Copyright (c) 2025 BMad Code, LLC. MIT License: see LICENSE.md in this folder. UltraCode Goal ships this copy so a run never depends on BMAD's deprecated shim, which BMAD removes at v7. -->
|
|
7
|
+
|
|
8
|
+
# Create Story Workflow
|
|
9
|
+
|
|
10
|
+
**Goal:** Create a comprehensive story file that gives the dev agent everything needed for flawless implementation.
|
|
11
|
+
|
|
12
|
+
**Your Role:** Story context engine that prevents LLM developer mistakes, omissions, or disasters.
|
|
13
|
+
- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
|
|
14
|
+
- Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent EVERYTHING needed for flawless implementation
|
|
15
|
+
- COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX, vague implementations, lying about completion, not learning from past work
|
|
16
|
+
- EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim! This is the most important function in the entire development process!
|
|
17
|
+
- UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different artifacts simultaneously and thoroughly
|
|
18
|
+
- SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is written
|
|
19
|
+
- ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents
|
|
20
|
+
|
|
21
|
+
Subagents, when the capability is available, are an important part of this workflow. Use them as directed by the workflow steps.
|
|
22
|
+
If you need an explicit user instruction to run them, ask once now for the whole workflow run.
|
|
23
|
+
|
|
24
|
+
## Conventions
|
|
25
|
+
|
|
26
|
+
- Bare paths (e.g. `discover-inputs.md`) resolve from the skill root.
|
|
27
|
+
- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
|
|
28
|
+
- `{project-root}`-prefixed paths resolve from the project working directory.
|
|
29
|
+
- `{skill-name}` resolves to the skill directory's basename.
|
|
30
|
+
|
|
31
|
+
## On Activation
|
|
32
|
+
|
|
33
|
+
### Step 1: Resolve the Workflow Block
|
|
34
|
+
|
|
35
|
+
Run: `uv run --no-project {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
|
|
36
|
+
|
|
37
|
+
**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
|
|
38
|
+
|
|
39
|
+
1. `{skill-root}/customize.toml`: defaults
|
|
40
|
+
2. `{project-root}/_bmad/custom/{skill-name}.toml`: team overrides
|
|
41
|
+
3. `{project-root}/_bmad/custom/{skill-name}.user.toml`: personal overrides
|
|
42
|
+
|
|
43
|
+
Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
|
|
44
|
+
|
|
45
|
+
### Step 2: Execute Prepend Steps
|
|
46
|
+
|
|
47
|
+
Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
|
|
48
|
+
|
|
49
|
+
### Step 3: Load Persistent Facts
|
|
50
|
+
|
|
51
|
+
Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}`; load the referenced contents as facts. All other entries are facts verbatim.
|
|
52
|
+
|
|
53
|
+
### Step 4: Load Config
|
|
54
|
+
|
|
55
|
+
Run `uv run --no-project {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` and resolve:
|
|
56
|
+
|
|
57
|
+
- `project_name`, `user_name`
|
|
58
|
+
- `communication_language`, `document_output_language`
|
|
59
|
+
- `user_skill_level`
|
|
60
|
+
- `planning_artifacts`, `implementation_artifacts`
|
|
61
|
+
- `date` as system-generated current datetime
|
|
62
|
+
|
|
63
|
+
If that script is absent or fails, read the same keys from `{project-root}/_bmad/config.yaml` and `config.user.yaml` (the root and the `bmm` section), falling back to `{project-root}/_bmad/bmm/config.yaml`.
|
|
64
|
+
|
|
65
|
+
When the invocation passes an `implementation_artifacts` folder, use it in place of the config's value, for `sprint-status.yaml` and the story files alike. An UltraCode Goal run passes its own folder, which can differ from BMAD's (a customized folder, or an isolated track), so the story file it writes and the sprint-status row it moves are the ones the run reads.
|
|
66
|
+
|
|
67
|
+
### Step 5: Greet the User
|
|
68
|
+
|
|
69
|
+
Greet `{user_name}`, speaking in `{communication_language}`.
|
|
70
|
+
|
|
71
|
+
### Step 6: Execute Append Steps
|
|
72
|
+
|
|
73
|
+
Execute each entry in `{workflow.activation_steps_append}` in order.
|
|
74
|
+
|
|
75
|
+
Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
|
|
76
|
+
|
|
77
|
+
## Paths
|
|
78
|
+
|
|
79
|
+
- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
|
|
80
|
+
- `epics_file` = `{planning_artifacts}/epics.md`
|
|
81
|
+
- `prd_file` = `{planning_artifacts}/prd.md`
|
|
82
|
+
- `architecture_file` = `{planning_artifacts}/architecture.md`
|
|
83
|
+
- `ux_file` = `{planning_artifacts}/*ux*.md`
|
|
84
|
+
- `story_title` = "" (will be elicited if not derivable)
|
|
85
|
+
- `default_output_file` = `{implementation_artifacts}/{{story_key}}.md`
|
|
86
|
+
|
|
87
|
+
## Input Files
|
|
88
|
+
|
|
89
|
+
| Input | Description | Path Pattern(s) | Load Strategy |
|
|
90
|
+
|-------|-------------|------------------|---------------|
|
|
91
|
+
| prd | PRD (fallback - epics file should have most content) | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | SELECTIVE_LOAD |
|
|
92
|
+
| architecture | Architecture (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | SELECTIVE_LOAD |
|
|
93
|
+
| ux | UX design (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | SELECTIVE_LOAD |
|
|
94
|
+
| epics | Enhanced epics+stories file with BDD and source hints | whole: `{planning_artifacts}/*epic*.md`, sharded: `{planning_artifacts}/*epic*/*.md` | SELECTIVE_LOAD |
|
|
95
|
+
|
|
96
|
+
## Execution
|
|
97
|
+
|
|
98
|
+
<workflow>
|
|
99
|
+
|
|
100
|
+
<step n="1" goal="Determine target story">
|
|
101
|
+
<check if="{{story_path}} is provided by user or user provided the epic and story number such as 2-4 or 1.6 or epic 1 story 5">
|
|
102
|
+
<action>Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth"</action>
|
|
103
|
+
<action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action>
|
|
104
|
+
<action>GOTO step 2a</action>
|
|
105
|
+
</check>
|
|
106
|
+
|
|
107
|
+
<action>Check if {{sprint_status}} file exists for auto discover</action>
|
|
108
|
+
<check if="sprint status file does NOT exist">
|
|
109
|
+
<output>🚫 No sprint status file found and no story specified</output>
|
|
110
|
+
<output>
|
|
111
|
+
**Required Options:**
|
|
112
|
+
1. Run `sprint-planning` to initialize sprint tracking (recommended)
|
|
113
|
+
2. Provide specific epic-story number to create (e.g., "1-2-user-auth")
|
|
114
|
+
3. Provide path to story documents if sprint status doesn't exist yet
|
|
115
|
+
</output>
|
|
116
|
+
<ask>Choose option [1], provide epic-story number, path to story docs, or [q] to quit:</ask>
|
|
117
|
+
|
|
118
|
+
<check if="user chooses 'q'">
|
|
119
|
+
<action>HALT - No work needed</action>
|
|
120
|
+
</check>
|
|
121
|
+
|
|
122
|
+
<check if="user chooses '1'">
|
|
123
|
+
<output>Run sprint-planning workflow first to create sprint-status.yaml</output>
|
|
124
|
+
<action>HALT - User needs to run sprint-planning</action>
|
|
125
|
+
</check>
|
|
126
|
+
|
|
127
|
+
<check if="user provides epic-story number">
|
|
128
|
+
<action>Parse user input: extract epic_num, story_num, story_title</action>
|
|
129
|
+
<action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action>
|
|
130
|
+
<action>GOTO step 2a</action>
|
|
131
|
+
</check>
|
|
132
|
+
|
|
133
|
+
<check if="user provides story docs path">
|
|
134
|
+
<action>Use user-provided path for story documents</action>
|
|
135
|
+
<action>GOTO step 2a</action>
|
|
136
|
+
</check>
|
|
137
|
+
</check>
|
|
138
|
+
|
|
139
|
+
<!-- Auto-discover from sprint status only if no user input -->
|
|
140
|
+
<check if="no user input provided">
|
|
141
|
+
<critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical>
|
|
142
|
+
<action>Load the FULL file: {{sprint_status}}</action>
|
|
143
|
+
<action>Read ALL lines from beginning to end - do not skip any content</action>
|
|
144
|
+
<action>Parse the development_status section completely</action>
|
|
145
|
+
|
|
146
|
+
<action>Find the FIRST story (by reading in order from top to bottom) where:
|
|
147
|
+
- Key matches pattern: number-number-name (e.g., "1-2-user-auth")
|
|
148
|
+
- NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
|
|
149
|
+
- Status value equals "backlog"
|
|
150
|
+
</action>
|
|
151
|
+
|
|
152
|
+
<check if="no backlog story found">
|
|
153
|
+
<output>📋 No backlog stories found in sprint-status.yaml
|
|
154
|
+
|
|
155
|
+
All stories are either already created, in progress, or done.
|
|
156
|
+
|
|
157
|
+
**Options:**
|
|
158
|
+
1. Run sprint-planning to refresh story tracking
|
|
159
|
+
2. Load PM agent and run correct-course to add more stories
|
|
160
|
+
3. Check if current sprint is complete and run retrospective
|
|
161
|
+
</output>
|
|
162
|
+
<action>HALT</action>
|
|
163
|
+
</check>
|
|
164
|
+
|
|
165
|
+
<action>Extract from found story key (e.g., "1-2-user-authentication"):
|
|
166
|
+
- epic_num: first number before dash (e.g., "1")
|
|
167
|
+
- story_num: second number after first dash (e.g., "2")
|
|
168
|
+
- story_title: remainder after second dash (e.g., "user-authentication")
|
|
169
|
+
</action>
|
|
170
|
+
<action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
|
|
171
|
+
<action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
|
|
172
|
+
|
|
173
|
+
<!-- Mark epic as in-progress if this is first story -->
|
|
174
|
+
<action>Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern</action>
|
|
175
|
+
<check if="this is first story in epic {{epic_num}}">
|
|
176
|
+
<action>Load {{sprint_status}} and check epic-{{epic_num}} status</action>
|
|
177
|
+
<action>If epic status is "backlog" → update to "in-progress"</action>
|
|
178
|
+
<action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action>
|
|
179
|
+
<action>If epic status is "in-progress" → no change needed</action>
|
|
180
|
+
<check if="epic status is 'done'">
|
|
181
|
+
<output>🚫 ERROR: Cannot create story in completed epic</output>
|
|
182
|
+
<output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output>
|
|
183
|
+
<output>If you need to add more work, either:</output>
|
|
184
|
+
<output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output>
|
|
185
|
+
<output>2. Create a new epic for additional work</output>
|
|
186
|
+
<action>HALT - Cannot proceed</action>
|
|
187
|
+
</check>
|
|
188
|
+
<check if="epic status is not one of: backlog, contexted, in-progress, done">
|
|
189
|
+
<output>🚫 ERROR: Invalid epic status '{{epic_status}}'</output>
|
|
190
|
+
<output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output>
|
|
191
|
+
<output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output>
|
|
192
|
+
<action>HALT - Cannot proceed</action>
|
|
193
|
+
</check>
|
|
194
|
+
<output>📊 Epic {{epic_num}} status updated to in-progress</output>
|
|
195
|
+
</check>
|
|
196
|
+
|
|
197
|
+
<action>GOTO step 2a</action>
|
|
198
|
+
</check>
|
|
199
|
+
<action>Load the FULL file: {{sprint_status}}</action>
|
|
200
|
+
<action>Read ALL lines from beginning to end - do not skip any content</action>
|
|
201
|
+
<action>Parse the development_status section completely</action>
|
|
202
|
+
|
|
203
|
+
<action>Find the FIRST story (by reading in order from top to bottom) where:
|
|
204
|
+
- Key matches pattern: number-number-name (e.g., "1-2-user-auth")
|
|
205
|
+
- NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
|
|
206
|
+
- Status value equals "backlog"
|
|
207
|
+
</action>
|
|
208
|
+
|
|
209
|
+
<check if="no backlog story found">
|
|
210
|
+
<output>No backlog stories found in sprint-status.yaml
|
|
211
|
+
|
|
212
|
+
All stories are either already created, in progress, or done.
|
|
213
|
+
|
|
214
|
+
**Options:**
|
|
215
|
+
1. Run sprint-planning to refresh story tracking
|
|
216
|
+
2. Load PM agent and run correct-course to add more stories
|
|
217
|
+
3. Check if current sprint is complete and run retrospective
|
|
218
|
+
</output>
|
|
219
|
+
<action>HALT</action>
|
|
220
|
+
</check>
|
|
221
|
+
|
|
222
|
+
<action>Extract from found story key (e.g., "1-2-user-authentication"):
|
|
223
|
+
- epic_num: first number before dash (e.g., "1")
|
|
224
|
+
- story_num: second number after first dash (e.g., "2")
|
|
225
|
+
- story_title: remainder after second dash (e.g., "user-authentication")
|
|
226
|
+
</action>
|
|
227
|
+
<action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
|
|
228
|
+
<action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
|
|
229
|
+
|
|
230
|
+
<!-- Mark epic as in-progress if this is first story -->
|
|
231
|
+
<action>Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern</action>
|
|
232
|
+
<check if="this is first story in epic {{epic_num}}">
|
|
233
|
+
<action>Load {{sprint_status}} and check epic-{{epic_num}} status</action>
|
|
234
|
+
<action>If epic status is "backlog" → update to "in-progress"</action>
|
|
235
|
+
<action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action>
|
|
236
|
+
<action>If epic status is "in-progress" → no change needed</action>
|
|
237
|
+
<check if="epic status is 'done'">
|
|
238
|
+
<output>ERROR: Cannot create story in completed epic</output>
|
|
239
|
+
<output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output>
|
|
240
|
+
<output>If you need to add more work, either:</output>
|
|
241
|
+
<output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output>
|
|
242
|
+
<output>2. Create a new epic for additional work</output>
|
|
243
|
+
<action>HALT - Cannot proceed</action>
|
|
244
|
+
</check>
|
|
245
|
+
<check if="epic status is not one of: backlog, contexted, in-progress, done">
|
|
246
|
+
<output>ERROR: Invalid epic status '{{epic_status}}'</output>
|
|
247
|
+
<output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output>
|
|
248
|
+
<output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output>
|
|
249
|
+
<action>HALT - Cannot proceed</action>
|
|
250
|
+
</check>
|
|
251
|
+
<output>Epic {{epic_num}} status updated to in-progress</output>
|
|
252
|
+
</check>
|
|
253
|
+
|
|
254
|
+
<action>GOTO step 2a</action>
|
|
255
|
+
</step>
|
|
256
|
+
|
|
257
|
+
<step n="2" goal="Load and analyze core artifacts">
|
|
258
|
+
<critical>🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer mistakes!</critical>
|
|
259
|
+
|
|
260
|
+
<!-- Load all available content through discovery protocol -->
|
|
261
|
+
<action>Read fully and follow `./discover-inputs.md` to load all input files</action>
|
|
262
|
+
<note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, plus any facts loaded during activation via `persistent_facts` (empty unless the user opted in).</note>
|
|
263
|
+
|
|
264
|
+
<!-- Analyze epics file for story foundation -->
|
|
265
|
+
<action>From {epics_content}, extract Epic {{epic_num}} complete context:</action> **EPIC ANALYSIS:** - Epic
|
|
266
|
+
objectives and business value - ALL stories in this epic for cross-story context - Our specific story's requirements, user story
|
|
267
|
+
statement, acceptance criteria - Technical requirements and constraints - Dependencies on other stories/epics - Source hints pointing to
|
|
268
|
+
original documents <!-- Extract specific story requirements -->
|
|
269
|
+
<action>Extract our story ({{epic_num}}-{{story_num}}) details:</action> **STORY FOUNDATION:** - User story statement
|
|
270
|
+
(As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story -
|
|
271
|
+
Business context and value - Success criteria <!-- Previous story analysis for context continuity -->
|
|
272
|
+
<check if="story_num > 1">
|
|
273
|
+
<action>Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}}</action>
|
|
274
|
+
<action>Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md</action> **PREVIOUS STORY INTELLIGENCE:** -
|
|
275
|
+
Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their
|
|
276
|
+
patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established <action>Extract
|
|
277
|
+
all learnings that could impact current story implementation</action>
|
|
278
|
+
</check>
|
|
279
|
+
|
|
280
|
+
<!-- Git intelligence for previous work patterns -->
|
|
281
|
+
<check
|
|
282
|
+
if="previous story exists AND git repository detected">
|
|
283
|
+
<action>Get last 5 commit titles to understand recent work patterns</action>
|
|
284
|
+
<action>Analyze 1-5 most recent commits for relevance to current story:
|
|
285
|
+
- Files created/modified
|
|
286
|
+
- Code patterns and conventions used
|
|
287
|
+
- Library dependencies added/changed
|
|
288
|
+
- Architecture decisions implemented
|
|
289
|
+
- Testing approaches used
|
|
290
|
+
</action>
|
|
291
|
+
<action>Extract actionable insights for current story implementation</action>
|
|
292
|
+
</check>
|
|
293
|
+
</step>
|
|
294
|
+
|
|
295
|
+
<step n="3" goal="Architecture analysis for developer guardrails">
|
|
296
|
+
<critical>🏗️ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow!</critical> **ARCHITECTURE DOCUMENT ANALYSIS:** <action>Systematically
|
|
297
|
+
analyze architecture content for story-relevant requirements:</action>
|
|
298
|
+
|
|
299
|
+
<!-- Load architecture - single file or sharded -->
|
|
300
|
+
<check if="architecture file is single file">
|
|
301
|
+
<action>Load complete {architecture_content}</action>
|
|
302
|
+
</check>
|
|
303
|
+
<check if="architecture is sharded to folder">
|
|
304
|
+
<action>Load architecture index and scan all architecture files</action>
|
|
305
|
+
</check> **CRITICAL ARCHITECTURE EXTRACTION:** <action>For
|
|
306
|
+
each architecture section, determine if relevant to this story:</action> - **Technical Stack:** Languages, frameworks, libraries with
|
|
307
|
+
versions - **Code Structure:** Folder organization, naming conventions, file patterns - **API Patterns:** Service structure, endpoint
|
|
308
|
+
patterns, data contracts - **Database Schemas:** Tables, relationships, constraints relevant to story - **Security Requirements:**
|
|
309
|
+
Authentication patterns, authorization rules - **Performance Requirements:** Caching strategies, optimization patterns - **Testing
|
|
310
|
+
Standards:** Testing frameworks, coverage expectations, test patterns - **Deployment Patterns:** Environment configurations, build
|
|
311
|
+
processes - **Integration Patterns:** External service integrations, data flows <action>Extract any story-specific requirements that the
|
|
312
|
+
developer MUST follow</action>
|
|
313
|
+
<action>Identify any architectural decisions that override previous patterns</action>
|
|
314
|
+
|
|
315
|
+
<!-- Read existing code being modified: non-negotiable -->
|
|
316
|
+
<critical>📂 READ FILES BEING MODIFIED: skipping this is the primary cause of implementation failures and review cycles</critical>
|
|
317
|
+
<action>From the architecture directory structure, identify every file marked UPDATE (not NEW) that this story will touch</action>
|
|
318
|
+
<action>Read each relevant UPDATE file completely. For each one, document in dev notes:
|
|
319
|
+
- Current state: what it does today (state machine, API calls, data shapes, existing behaviors)
|
|
320
|
+
- What this story changes: the specific sections or behaviors being modified
|
|
321
|
+
- What must be preserved: existing interactions and behaviors the story must not break
|
|
322
|
+
</action>
|
|
323
|
+
<critical>A story implementation must leave the system working end-to-end, not just satisfy its stated ACs.
|
|
324
|
+
If a behavior is required for the feature to work correctly in the existing system, it is a requirement
|
|
325
|
+
whether or not it is explicitly written in the story. The dev agent owns this.</critical>
|
|
326
|
+
</step>
|
|
327
|
+
|
|
328
|
+
<step n="4" goal="Web research for latest technical specifics">
|
|
329
|
+
<critical>🌐 ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations!</critical> **WEB INTELLIGENCE:** <action>Identify specific
|
|
330
|
+
technical areas that require latest version knowledge:</action>
|
|
331
|
+
|
|
332
|
+
<!-- Check for libraries/frameworks mentioned in architecture -->
|
|
333
|
+
<action>From architecture analysis, identify specific libraries, APIs, or
|
|
334
|
+
frameworks</action>
|
|
335
|
+
<action>For each critical technology, research latest stable version and key changes:
|
|
336
|
+
- Latest API documentation and breaking changes
|
|
337
|
+
- Security vulnerabilities or updates
|
|
338
|
+
- Performance improvements or deprecations
|
|
339
|
+
- Best practices for current version
|
|
340
|
+
</action>
|
|
341
|
+
**EXTERNAL CONTEXT INCLUSION:** <action>Include in story any critical latest information the developer needs:
|
|
342
|
+
- Specific library versions and why chosen
|
|
343
|
+
- API endpoints with parameters and authentication
|
|
344
|
+
- Recent security patches or considerations
|
|
345
|
+
- Performance optimization techniques
|
|
346
|
+
- Migration considerations if upgrading
|
|
347
|
+
</action>
|
|
348
|
+
</step>
|
|
349
|
+
|
|
350
|
+
<step n="5" goal="Create comprehensive story file">
|
|
351
|
+
<critical>📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide!</critical>
|
|
352
|
+
|
|
353
|
+
<action>Initialize from template.md:
|
|
354
|
+
{default_output_file}</action>
|
|
355
|
+
<template-output file="{default_output_file}">story_header</template-output>
|
|
356
|
+
|
|
357
|
+
<!-- Story foundation from epics analysis -->
|
|
358
|
+
<template-output
|
|
359
|
+
file="{default_output_file}">story_requirements</template-output>
|
|
360
|
+
|
|
361
|
+
<!-- Developer context section - MOST IMPORTANT PART -->
|
|
362
|
+
<template-output file="{default_output_file}">
|
|
363
|
+
developer_context_section</template-output> **DEV AGENT GUARDRAILS:** <template-output file="{default_output_file}">
|
|
364
|
+
technical_requirements</template-output>
|
|
365
|
+
<template-output file="{default_output_file}">architecture_compliance</template-output>
|
|
366
|
+
<template-output
|
|
367
|
+
file="{default_output_file}">library_framework_requirements</template-output>
|
|
368
|
+
<template-output file="{default_output_file}">
|
|
369
|
+
file_structure_requirements</template-output>
|
|
370
|
+
<template-output file="{default_output_file}">testing_requirements</template-output>
|
|
371
|
+
|
|
372
|
+
<!-- Previous story intelligence -->
|
|
373
|
+
<check
|
|
374
|
+
if="previous story learnings available">
|
|
375
|
+
<template-output file="{default_output_file}">previous_story_intelligence</template-output>
|
|
376
|
+
</check>
|
|
377
|
+
|
|
378
|
+
<!-- Git intelligence -->
|
|
379
|
+
<check
|
|
380
|
+
if="git analysis completed">
|
|
381
|
+
<template-output file="{default_output_file}">git_intelligence_summary</template-output>
|
|
382
|
+
</check>
|
|
383
|
+
|
|
384
|
+
<!-- Latest technical specifics -->
|
|
385
|
+
<check if="web research completed">
|
|
386
|
+
<template-output file="{default_output_file}">latest_tech_information</template-output>
|
|
387
|
+
</check>
|
|
388
|
+
|
|
389
|
+
<!-- Project context reference -->
|
|
390
|
+
<template-output
|
|
391
|
+
file="{default_output_file}">project_context_reference</template-output>
|
|
392
|
+
|
|
393
|
+
<!-- Final status update -->
|
|
394
|
+
<template-output file="{default_output_file}">
|
|
395
|
+
story_completion_status</template-output>
|
|
396
|
+
|
|
397
|
+
<!-- CRITICAL: Set status to ready-for-dev -->
|
|
398
|
+
<action>Set story Status to: "ready-for-dev"</action>
|
|
399
|
+
<action>Add completion note: "Ultimate
|
|
400
|
+
context engine analysis completed - comprehensive developer guide created"</action>
|
|
401
|
+
</step>
|
|
402
|
+
|
|
403
|
+
<step n="6" goal="Update sprint status and finalize">
|
|
404
|
+
<action>Validate the newly created story file {default_output_file} against `./checklist.md` and apply any required fixes before finalizing</action>
|
|
405
|
+
<action>Save story document unconditionally</action>
|
|
406
|
+
|
|
407
|
+
<!-- Update sprint status -->
|
|
408
|
+
<check if="sprint status file exists">
|
|
409
|
+
<action>Update {{sprint_status}}</action>
|
|
410
|
+
<action>Load the FULL file and read all development_status entries</action>
|
|
411
|
+
<action>Find development_status key matching {{story_key}}</action>
|
|
412
|
+
<action>Verify current status is "backlog" (expected previous state)</action>
|
|
413
|
+
<action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
|
|
414
|
+
<action>Update last_updated field to current date</action>
|
|
415
|
+
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
|
416
|
+
</check>
|
|
417
|
+
|
|
418
|
+
<action>Report completion</action>
|
|
419
|
+
<output>**🎯 ULTIMATE BMad Method STORY CONTEXT CREATED, {user_name}!**
|
|
420
|
+
|
|
421
|
+
**Story Details:**
|
|
422
|
+
- Story ID: {{story_id}}
|
|
423
|
+
- Story Key: {{story_key}}
|
|
424
|
+
- File: {{story_file}}
|
|
425
|
+
- Status: ready-for-dev
|
|
426
|
+
|
|
427
|
+
**Next Steps:**
|
|
428
|
+
1. Review the comprehensive story in {{story_file}}
|
|
429
|
+
2. Run `ucg-dev-story` for optimized implementation
|
|
430
|
+
3. Run `code-review` when complete (auto-marks done)
|
|
431
|
+
4. Optional: If Test Architect module installed, run `/bmad:tea:automate` after `ucg-dev-story` to generate guardrail tests
|
|
432
|
+
|
|
433
|
+
**The developer now has everything needed for flawless implementation!**
|
|
434
|
+
</output>
|
|
435
|
+
<action>Run: `uv run --no-project {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`; if the script fails, take `on_complete` from the `workflow` block resolved on activation. If the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
|
|
436
|
+
</step>
|
|
437
|
+
|
|
438
|
+
</workflow>
|