Skip to content

Commit 1945161

Browse files
author
Matthew
committed
Merge branch 'docs/post-mvp-epics' into 'main'
docs(standards): add post-MVP epics and stories (10-13) See merge request orgdocs/development-standards!28
2 parents dc0f611 + c1edc36 commit 1945161

9 files changed

Lines changed: 499 additions & 0 deletions

‎_bmad-output/implementation-artifacts/10-1-configure-gitlab-github-mirror-ci.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Story 10.1: Configure GitLab-to-GitHub Mirror CI
2+
3+
Status: ready-for-dev
4+
5+
## Story
6+
7+
As a maintainer,
8+
I want the GitLab CI pipeline to automatically mirror pushes to main to the GitHub remote,
9+
so that the GitHub mirror stays in sync without manual intervention.
10+
11+
## Acceptance Criteria
12+
13+
1. The `mirror-to-github` job in `.gitlab-ci.yml` runs successfully on pushes to main
14+
2. A `$GITHUB_MIRROR_SSH_KEY` CI/CD variable is configured in the GitLab project settings
15+
3. The GitHub mirror (`devrail-dev/devrail-standards`) is automatically updated within minutes of a push to GitLab main
16+
4. The mirror job uses a deploy key (not a personal SSH key) for security
17+
18+
## Tasks / Subtasks
19+
20+
- [ ] Task 1: Generate a dedicated SSH deploy key for GitHub mirroring (AC: 4)
21+
- [ ] 1.1 Generate a new SSH key pair specifically for the mirror job
22+
- [ ] 1.2 Add the public key as a deploy key on the `devrail-dev/devrail-standards` GitHub repo (with write access)
23+
- [ ] 1.3 Add the private key as `$GITHUB_MIRROR_SSH_KEY` CI/CD variable in the GitLab project (masked, protected)
24+
25+
- [ ] Task 2: Verify the mirror job runs (AC: 1, 2, 3)
26+
- [ ] 2.1 Push a trivial commit to main and verify the `mirror-to-github` job triggers
27+
- [ ] 2.2 Confirm the GitHub mirror reflects the latest GitLab main commit
28+
- [ ] 2.3 Verify the job completes in under 30 seconds
29+
30+
## Dev Notes
31+
32+
- The `.gitlab-ci.yml` already has the `mirror-to-github` job configured — it just needs the CI variable
33+
- The job uses `alpine:latest` with `git` and `openssh-client` installed at runtime
34+
- The job runs `git push --force` to the GitHub remote — this is safe since GitLab is the source of truth
35+
- The job is gated on `$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $GITHUB_MIRROR_SSH_KEY`
36+
- Current SSH key (`~/.ssh/matthew@mellor.earth`) should NOT be used — create a purpose-built deploy key
37+
38+
### References
39+
40+
- [Source: .gitlab-ci.yml] — mirror-to-github job definition
41+
- [Source: repos.md] — repo map and remote configuration
42+
43+
## Dev Agent Record
44+
45+
### Agent Model Used
46+
47+
### Debug Log References
48+
49+
### Completion Notes List
50+
51+
### File List

‎_bmad-output/implementation-artifacts/10-2-fix-version-manifest-ci-job.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Story 10.2: Fix Version-Manifest CI Job for Releases
2+
3+
Status: ready-for-dev
4+
5+
## Story
6+
7+
As a maintainer,
8+
I want the version-manifest CI job to generate and attach a tool version report to each GitHub release,
9+
so that users can see exactly which tool versions are included in each container image.
10+
11+
## Acceptance Criteria
12+
13+
1. The `version-manifest` job in `build.yml` runs successfully on tag pushes
14+
2. The tool version manifest (markdown file) is attached as an asset to the GitHub release
15+
3. The manifest includes versions for all tools across all 8 language ecosystems
16+
4. The devrail.dev versions page is updated (if auto-generated from release assets)
17+
18+
## Tasks / Subtasks
19+
20+
- [ ] Task 1: Investigate why the version-manifest job was skipped in v1.6.0 (AC: 1)
21+
- [ ] 1.1 Review `build.yml` workflow to understand the version-manifest job's trigger conditions
22+
- [ ] 1.2 Check the v1.6.0 build run logs for the version-manifest job
23+
- [ ] 1.3 Identify the root cause (conditional gate, dependency, permissions, or other)
24+
25+
- [ ] Task 2: Fix the version-manifest job (AC: 1, 2)
26+
- [ ] 2.1 Apply the fix based on root cause analysis
27+
- [ ] 2.2 Verify the fix doesn't break other jobs in the build pipeline
28+
29+
- [ ] Task 3: Verify the manifest content (AC: 3)
30+
- [ ] 3.1 Run `scripts/report-tool-versions.sh` locally inside the container to validate output
31+
- [ ] 3.2 Confirm all 8 language ecosystems are represented
32+
- [ ] 3.3 Confirm Terragrunt version is included
33+
34+
- [ ] Task 4: Verify devrail.dev versions page (AC: 4)
35+
- [ ] 4.1 Check if the devrail.dev site has automation to pull version manifests from releases
36+
- [ ] 4.2 If automated, verify it picks up the new release asset
37+
- [ ] 4.3 If manual, update the versions page content
38+
39+
## Dev Notes
40+
41+
- The `version-manifest` job was added as part of the tool version manifest feature (Story 2.9 / PR #4)
42+
- The job ran for 0 seconds in the v1.6.0 build — likely skipped by a conditional
43+
- `scripts/report-tool-versions.sh` is the script that generates the manifest inside the container
44+
- The devrail.dev site had a PR (#5) for `/docs/container/versions/` with CI-generated markdown
45+
- The build workflow is at `dev-toolchain/.github/workflows/build.yml`
46+
47+
### References
48+
49+
- [Source: dev-toolchain/.github/workflows/build.yml] — build and release pipeline
50+
- [Source: dev-toolchain/scripts/report-tool-versions.sh] — version manifest generator
51+
- [Source: devrail.dev PR #5] — versions page on documentation site
52+
53+
## Dev Agent Record
54+
55+
### Agent Model Used
56+
57+
### Debug Log References
58+
59+
### Completion Notes List
60+
61+
### File List

‎_bmad-output/implementation-artifacts/10-3-write-v160-release-blog-post.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Story 10.3: Write v1.6.0 Release Blog Post
2+
3+
Status: ready-for-dev
4+
5+
## Story
6+
7+
As a maintainer,
8+
I want to publish a blog post announcing the v1.6.0 release,
9+
so that users understand the new capabilities available in the latest dev-toolchain container.
10+
11+
## Acceptance Criteria
12+
13+
1. Blog post is created at `devrail.dev/content/blog/2026-03-09-v160-release.md`
14+
2. Post covers all major features in v1.6.0: Rust ecosystem, Terragrunt support, `make fix`, pre-push hooks, `make release`, tool version manifest
15+
3. Post follows the existing blog post format and Hugo/Docsy front matter conventions
16+
4. Post is deployed to devrail.dev via PR and Cloudflare Pages
17+
5. `make check` passes on the devrail.dev repo
18+
19+
## Tasks / Subtasks
20+
21+
- [ ] Task 1: Write the blog post (AC: 1, 2, 3)
22+
- [ ] 1.1 Review existing blog posts for format and tone (`2026-03-02-introducing-devrail.md`, Rust post, Terragrunt post)
23+
- [ ] 1.2 Write post covering: Rust ecosystem (clippy, rustfmt, cargo-audit, cargo-deny), Terragrunt companion tool, `make fix` target, pre-push hooks, `make release` script, tool version manifest, conventional commit scope update (v1.1.0)
24+
- [ ] 1.3 Include container pull command and upgrade instructions
25+
- [ ] 1.4 Include link to full CHANGELOG
26+
27+
- [ ] Task 2: Create PR and deploy (AC: 4, 5)
28+
- [ ] 2.1 Create feature branch in devrail.dev repo
29+
- [ ] 2.2 Run `make check` to validate
30+
- [ ] 2.3 Create PR and merge after CI passes
31+
- [ ] 2.4 Verify deployment to devrail.dev
32+
33+
## Dev Notes
34+
35+
- Previous blog posts exist at `devrail.dev/content/blog/`:
36+
- `2026-03-02-introducing-devrail.md` — launch announcement
37+
- `2026-03-04-rust-support.md` — Rust ecosystem announcement
38+
- `2026-03-05-terragrunt-support.md` — Terragrunt announcement
39+
- v1.6.0 is a "mega release" combining many features — the post should be comprehensive but not duplicate existing Rust/Terragrunt posts (link to them instead)
40+
- Hugo/Docsy front matter: title, date, description, author, tags
41+
- Cloudflare Pages deploys automatically on merge to main
42+
43+
### References
44+
45+
- [Source: devrail.dev/content/blog/] — existing blog posts for format reference
46+
- [Source: dev-toolchain/CHANGELOG.md] — v1.6.0 release notes
47+
- [Source: GitHub Release v1.6.0] — release notes and assets
48+
49+
## Dev Agent Record
50+
51+
### Agent Model Used
52+
53+
### Debug Log References
54+
55+
### Completion Notes List
56+
57+
### File List

‎_bmad-output/implementation-artifacts/11-1-design-devrail-init-cli.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Story 11.1: Design `devrail init` CLI and Adoption Script
2+
3+
Status: ready-for-dev
4+
5+
## Story
6+
7+
As a developer adopting DevRail,
8+
I want to run a single command that scaffolds all DevRail configuration files for my project,
9+
so that I can progressively integrate DevRail without manually copying files from templates.
10+
11+
## Acceptance Criteria
12+
13+
1. A design document exists specifying the `devrail init` CLI interface, options, and behavior
14+
2. The design covers all three adoption paths: partial (wedge), retrofit (brownfield), and template (greenfield)
15+
3. The design specifies which files are generated and how existing files are handled (merge vs overwrite vs skip)
16+
4. The design addresses `.devrail.yml` as the input configuration driving all scaffolding
17+
5. The design is validated against the PRD Phase 2a requirements
18+
19+
## Tasks / Subtasks
20+
21+
- [ ] Task 1: Research existing adoption patterns (AC: 2)
22+
- [ ] 1.1 Review the product brief's Phase 2a description
23+
- [ ] 1.2 Catalog what files `make init` currently generates inside the container
24+
- [ ] 1.3 Identify gaps between `make init` and a full `devrail init` experience
25+
- [ ] 1.4 Document the three adoption paths and what each requires
26+
27+
- [ ] Task 2: Design the CLI interface (AC: 1, 3, 4)
28+
- [ ] 2.1 Define command syntax: `devrail init [options]`
29+
- [ ] 2.2 Define options: `--languages`, `--ci-platform`, `--force`, `--dry-run`, etc.
30+
- [ ] 2.3 Specify file generation matrix: which files for which languages/platforms
31+
- [ ] 2.4 Define conflict resolution strategy (existing files: prompt, skip, merge, overwrite)
32+
- [ ] 2.5 Define `.devrail.yml` as the primary input with interactive prompts as fallback
33+
34+
- [ ] Task 3: Write the design document (AC: 1, 5)
35+
- [ ] 3.1 Create design doc in `_bmad-output/planning-artifacts/`
36+
- [ ] 3.2 Include CLI interface specification
37+
- [ ] 3.3 Include file generation matrix
38+
- [ ] 3.4 Include adoption path workflows
39+
- [ ] 3.5 Validate against PRD Phase 2a requirements
40+
41+
## Dev Notes
42+
43+
- `make init` / `make _init` already exists in dev-toolchain (Story 1.4.0) — scaffolds ruff.toml, .shellcheckrc, .tflint.hcl, etc.
44+
- `devrail init` would be a HOST-side script (not container-side) that also generates: .devrail.yml, .pre-commit-config.yaml, Makefile, CLAUDE.md, AGENTS.md, .cursorrules, .github/ or .gitlab-ci.yml, DEVELOPMENT.md
45+
- The script should be distributable as a single shell script (curl-pipe-bash pattern) or via npm/pip
46+
- Key question: should this be a new repo (`devrail-cli`) or live in `dev-toolchain`?
47+
- Product brief Phase 2a: "devrail init adoption script for progressive DevRail integration"
48+
49+
### References
50+
51+
- [Source: product-brief-development-standards-2026-03-06.md] — Phase 2a description
52+
- [Source: dev-toolchain/Makefile] — existing `make init` target
53+
- [Source: github-repo-template/] — greenfield template files
54+
- [Source: gitlab-repo-template/] — greenfield template files
55+
56+
## Dev Agent Record
57+
58+
### Agent Model Used
59+
60+
### Debug Log References
61+
62+
### Completion Notes List
63+
64+
### File List

‎_bmad-output/implementation-artifacts/11-2-implement-devrail-init-core.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Story 11.2: Implement `devrail init` Core Script
2+
3+
Status: backlog
4+
5+
## Story
6+
7+
As a developer adopting DevRail,
8+
I want `devrail init` to generate all required configuration files based on my `.devrail.yml`,
9+
so that my project is DevRail-compliant with a single command.
10+
11+
## Acceptance Criteria
12+
13+
1. Running `devrail init` in a project directory generates all standard DevRail files
14+
2. The script reads `.devrail.yml` to determine languages, CI platform, and options
15+
3. If no `.devrail.yml` exists, the script prompts interactively to create one
16+
4. Existing files are handled per the conflict resolution strategy (prompt by default)
17+
5. Generated files match the current template repos (github-repo-template, gitlab-repo-template)
18+
6. The script is idempotent — safe to re-run
19+
7. `--dry-run` shows what would be generated without writing files
20+
21+
## Tasks / Subtasks
22+
23+
- [ ] Task 1: Implement core script (AC: 1, 2, 6)
24+
- [ ] 1.1 Create script following design from Story 11.1
25+
- [ ] 1.2 Implement `.devrail.yml` parsing
26+
- [ ] 1.3 Implement file generation for core files (Makefile, DEVELOPMENT.md, .editorconfig, .gitignore)
27+
- [ ] 1.4 Implement file generation for agent files (CLAUDE.md, AGENTS.md, .cursorrules)
28+
- [ ] 1.5 Implement file generation for pre-commit config (.pre-commit-config.yaml)
29+
- [ ] 1.6 Implement CI platform detection and generation (.github/workflows or .gitlab-ci.yml)
30+
31+
- [ ] Task 2: Implement interactive mode (AC: 3)
32+
- [ ] 2.1 Add interactive prompts for language selection
33+
- [ ] 2.2 Add interactive prompts for CI platform selection
34+
- [ ] 2.3 Generate `.devrail.yml` from interactive responses
35+
36+
- [ ] Task 3: Implement conflict resolution (AC: 4)
37+
- [ ] 3.1 Detect existing files before generation
38+
- [ ] 3.2 Implement prompt/skip/overwrite/merge strategies
39+
- [ ] 3.3 Default to prompt when files exist
40+
41+
- [ ] Task 4: Implement --dry-run (AC: 7)
42+
- [ ] 4.1 Add --dry-run flag that shows planned file operations without writing
43+
44+
- [ ] Task 5: Test and validate (AC: 5)
45+
- [ ] 5.1 Test against empty directory (greenfield)
46+
- [ ] 5.2 Test against existing project (retrofit)
47+
- [ ] 5.3 Test idempotency (re-run produces no changes)
48+
- [ ] 5.4 Verify generated files match template repos
49+
50+
## Dev Notes
51+
52+
- Blocked by Story 11.1 (design must be completed first)
53+
- Implementation language TBD (bash script vs Go CLI vs Python CLI) — decided in 11.1
54+
- Must follow DevRail critical rules (idempotent scripts, shared logging, etc.)
55+
56+
### References
57+
58+
- [Source: Story 11.1 design document] — CLI specification
59+
- [Source: github-repo-template/] — reference files for generation
60+
- [Source: gitlab-repo-template/] — reference files for generation
61+
62+
## Dev Agent Record
63+
64+
### Agent Model Used
65+
66+
### Debug Log References
67+
68+
### Completion Notes List
69+
70+
### File List

‎_bmad-output/implementation-artifacts/11-3-distribute-and-document-devrail-init.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Story 11.3: Distribute and Document `devrail init`
2+
3+
Status: backlog
4+
5+
## Story
6+
7+
As a developer,
8+
I want to install `devrail init` easily and have clear documentation,
9+
so that I can adopt DevRail in my project without reading the full standards first.
10+
11+
## Acceptance Criteria
12+
13+
1. The `devrail init` script is available via a simple install command (curl, npm, pip, or similar)
14+
2. Installation instructions are documented on devrail.dev
15+
3. A getting-started guide walks through the full adoption flow
16+
4. The devrail.dev site includes a "Quick Start" page with `devrail init` as the entry point
17+
5. `make check` passes on all updated repos
18+
19+
## Tasks / Subtasks
20+
21+
- [ ] Task 1: Set up distribution (AC: 1)
22+
- [ ] 1.1 Choose distribution mechanism based on 11.1 design
23+
- [ ] 1.2 Publish the script/package to the chosen registry
24+
- [ ] 1.3 Test installation from scratch on a clean system
25+
26+
- [ ] Task 2: Write documentation (AC: 2, 3, 4)
27+
- [ ] 2.1 Add install instructions to devrail.dev
28+
- [ ] 2.2 Write getting-started guide covering all three adoption paths
29+
- [ ] 2.3 Update the devrail.dev Quick Start page
30+
- [ ] 2.4 Add CLI reference documentation
31+
32+
- [ ] Task 3: Validate end-to-end (AC: 5)
33+
- [ ] 3.1 Test full flow: install → init → make check (greenfield)
34+
- [ ] 3.2 Test full flow: install → init → make check (retrofit)
35+
- [ ] 3.3 Run `make check` on all updated repos
36+
37+
## Dev Notes
38+
39+
- Blocked by Story 11.2 (implementation must be completed first)
40+
- Distribution options to consider: GitHub releases (curl-pipe-bash), npm package, pip package, Homebrew tap
41+
- The devrail.dev site currently has Getting Started docs — these need updating, not replacing
42+
43+
### References
44+
45+
- [Source: devrail.dev/content/docs/] — existing documentation
46+
- [Source: Story 11.2] — implementation to distribute
47+
48+
## Dev Agent Record
49+
50+
### Agent Model Used
51+
52+
### Debug Log References
53+
54+
### Completion Notes List
55+
56+
### File List

0 commit comments

Comments
 (0)