From 6ffa0f818854230a5bd204c5012058ea8ed41a4a Mon Sep 17 00:00:00 2001 From: Jonathan Tsai Date: Sat, 28 Mar 2026 18:41:39 +0800 Subject: [PATCH] chore: add backlog-to-openspec phase 2.5 and development workflow docs - Add Phase 2.5 to backlog-to-openspec skill: auto-create feature branch - Update skill version to v1.1 - Add DEVELOPMENT_WORKFLOW.md with complete developer guide - Update INDEX.md with new contributor path - Update README.md with workflow docs link - Document chore/ workflow for infrastructure/tooling changes --- .opencode/skills/backlog-to-openspec/SKILL.md | 46 ++- README.md | 2 + docs/DEVELOPMENT_WORKFLOW.md | 371 ++++++++++++++++++ docs/INDEX.md | 29 ++ 4 files changed, 443 insertions(+), 5 deletions(-) create mode 100644 docs/DEVELOPMENT_WORKFLOW.md diff --git a/.opencode/skills/backlog-to-openspec/SKILL.md b/.opencode/skills/backlog-to-openspec/SKILL.md index 43f6cac..e2ec5e3 100644 --- a/.opencode/skills/backlog-to-openspec/SKILL.md +++ b/.opencode/skills/backlog-to-openspec/SKILL.md @@ -5,7 +5,7 @@ license: MIT compatibility: Requires openspec CLI. metadata: author: tryweb - version: "1.0" + version: "1.1" generatedBy: "manual" --- @@ -80,6 +80,37 @@ If a related archived change already exists, reuse patterns but do not copy stal --- +## Phase 2.5 — Create Feature Branch (CRITICAL) + +**Goal**: Keep code and specs together in the same branch for atomic commits. + +After creating the OpenSpec change, immediately create a feature branch: + +```bash +# Use the same change ID for consistency +CHANGE_ID="" + +# Create and push feature branch +git checkout -b "feat/${CHANGE_ID}" +git push origin "feat/${CHANGE_ID}" -u +``` + +**Why this matters**: +- Code and OpenSpec artifacts stay together in the same branch +- Enables atomic commits (code + specs in one commit) +- Aligns with `release-workflow` which expects feature work on branches + +**Branch naming convention**: +- Features: `feat/` +- Fixes: `fix/` +- Chores: `chore/` + +**If working tree is dirty**: +- Stash or commit current changes first +- Never mix unrelated work in the same branch + +--- + ## Phase 3 — Write Proposal (What/Why) In `proposal.md`, include: @@ -213,15 +244,19 @@ rg "BL-" docs/backlog.md # 2) create change openspec new change "" -# 3) inspect artifact state +# 3) create feature branch (IMPORTANT: do this before coding!) +git checkout -b "feat/" +git push origin "feat/" -u + +# 4) inspect artifact state openspec status --change "" --json -# 4) inspect artifact instructions +# 5) inspect artifact instructions openspec instructions proposal --change "" --json openspec instructions design --change "" --json openspec instructions tasks --change "" --json -# 5) final readiness check +# 6) final readiness check openspec status --change "" ``` @@ -235,4 +270,5 @@ This skill is complete for a backlog item only when: 2. Runtime surface and entrypoint are explicit 3. Verification matrix includes required unit/integration/e2e 4. Changelog wording class is defined (`internal-only` / `user-facing`) -5. Change is ready for `/opsx-apply` implementation +5. Feature branch is created and pushed (`feat/`) +6. Change is ready for `/opsx-apply` implementation diff --git a/README.md b/README.md index 8c15798..1facfd6 100644 --- a/README.md +++ b/README.md @@ -698,6 +698,8 @@ npm run typecheck npm run build ``` +For a complete development workflow guide (using OpenCode skills), see [DEVELOPMENT_WORKFLOW.md](docs/DEVELOPMENT_WORKFLOW.md). + ## Validation Commands The project provides layered validation workflows that can run locally or inside the Docker environment. diff --git a/docs/DEVELOPMENT_WORKFLOW.md b/docs/DEVELOPMENT_WORKFLOW.md new file mode 100644 index 0000000..54f6fbe --- /dev/null +++ b/docs/DEVELOPMENT_WORKFLOW.md @@ -0,0 +1,371 @@ +# Development Workflow Guide + +**Last Updated**: March 2026 +**Status**: Active +**Prerequisites**: OpenCode CLI, Git, GitHub CLI, Docker + +--- + +## Overview + +This project uses a standardized development workflow based on two OpenCode skills: + +1. **`backlog-to-openspec`** — Converts backlog items into implementation-ready specifications +2. **`release-workflow`** — Handles npm release with anti-drift gates + +Both skills are designed to keep code and specifications synchronized in the same git branch. + +### When to Use Which Workflow + +| Your Task | Use This | Branch | +|-----------|----------|--------| +| New feature from backlog | `backlog-to-openspec` | `feat/` | +| Bug fix | Direct `chore/` or `fix/` | `fix/` | +| Infrastructure, tools, docs | Direct `chore/` | `chore/` | +| Publish to npm | `release-workflow` | `release/vX.Y.Z` | + +--- + +## Prerequisites + +Before starting development, ensure you have: + +- [ ] OpenCode CLI installed (`1.2.27+`) +- [ ] Git configured with GitHub access +- [ ] GitHub CLI (`gh`) authenticated +- [ ] Docker and Docker Compose installed +- [ ] Node.js `24.x` (see `.nvmrc`) + +Verify authentication: + +```bash +npm whoami # Should return your npm username +gh auth status # Should show "Logged in to github.com" +``` + +--- + +## Development Workflow + +### Phase 1: From Backlog to Implementation + +Use this when you have a backlog item to implement. + +``` +┌─────────────────────┐ +│ 1. backlog-to-openspec │ +│ (use the skill) │ +└──────────┬────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 2. Feature Branch │ +│ Created + Pushed │ +└──────────┬────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 3. /opsx-apply │ +│ (implementation) │ +└──────────┬────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 4. Commit + Push │ +│ (code + specs) │ +└──────────┬────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 5. Create PR │ +│ (to main) │ +└──────────┬────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 6. Merge + Cleanup │ +└─────────────────────┘ +``` + +--- + +### Step 1: Use `backlog-to-openspec` Skill + +Trigger the skill with your backlog item: + +``` +/backlog-to-openspec +``` + +When prompted, provide: +- Backlog ID (e.g., `BL-014`) +- Or a brief description of what you want to build + +**What happens:** + +1. **Backlog Normalization** — Parses and validates the backlog item +2. **Create OpenSpec Change** — Runs `openspec new change ""` +3. **Create Feature Branch** — Creates `feat/` branch and pushes to origin ⭐ +4. **Write Proposal** — Documents problem, goal, scope +5. **Write Design** — Architecture decisions, runtime surface, entrypoint +6. **Write Specs** — Testable requirements with scenarios +7. **Build Tasks** — Atomic implementation tasks with verification matrix + +**Output:** +- OpenSpec artifacts in `.opencode/changes//` +- Feature branch: `feat/` + +--- + +### Step 2: Verify Feature Branch + +After the skill completes, confirm you're on the new branch: + +```bash +git branch +# Should show: * feat/ +``` + +If not, switch manually: + +```bash +git checkout feat/ +``` + +--- + +### Step 3: Implement with `/opsx-apply` + +Start implementation: + +``` +/opsx-apply +``` + +This will: +- Read the tasks from `tasks.md` +- Guide you through each implementation task +- Verify completion as you go + +--- + +### Step 4: Commit Changes + +Keep code and specs together in atomic commits: + +```bash +# Stage all changes (code + OpenSpec artifacts) +git add . + +# Commit with descriptive message +git commit -m "feat: implement + +- Proposal: docs/... +- Design: docs/... +- Specs: .opencode/changes//specs/ +- Tasks: .opencode/changes//tasks.md +- Code: src/... +- Tests: test/..." +``` + +**Why atomic commits matter:** +- Code and specifications stay synchronized +- Easier to rollback if needed +- Clear traceability from spec to implementation + +--- + +### Step 5: Push and Create PR + +```bash +# Push feature branch +git push origin feat/ + +# Create PR to main +gh pr create \ + --title "feat: - " \ + --body "$(cat <<'EOF' +## Summary +- Brief description of changes + +## Changes +- proposal.md: ... +- design.md: ... +- specs/: ... +- src/: ... + +## Testing +- [ ] Unit tests pass +- [ ] Integration tests pass +- [ ] E2E tests pass (if user-facing) +EOF +)" \ + --base main \ + --head feat/ +``` + +Wait for CI checks to pass, then merge. + +--- + +### Step 6: Cleanup + +After PR is merged: + +```bash +# Switch to main and pull latest +git checkout main && git pull origin main + +# Delete feature branch (optional) +git branch -d feat/ +``` + +--- + +## Release Workflow + +When you're ready to publish a new version: + +### Step 1: Use `release-workflow` Skill + +``` +/release-workflow +``` + +The skill will guide you through: + +1. **Local Preparation** — Run `npm run release:check` in Docker +2. **Claim-to-Evidence Gate** — Verify every changelog claim has evidence +3. **Operability Gate** — Verify user-facing features have runtime entrypoints +4. **Version & Changelog** — Update `package.json` and `CHANGELOG.md` +5. **Release Branch** — Create `release/vX.Y.Z` branch +6. **PR to Main** — Create PR with pre-merge checks +7. **Tag and Trigger CI** — Push tag to trigger npm publish +8. **Post-Release Verification** — Confirm npm + GitHub Release + +--- + +## Quick Reference + +### Common Commands + +```bash +# Start new feature +/backlog-to-openspec + +# Implement +/opsx-apply + +# Release +/release-workflow + +# Check current branch +git branch + +# Check status +git status --short +``` + +### Branch Naming Convention + +| Type | Format | Example | When to Use | +|------|--------|---------|-------------| +| Feature | `feat/` | `feat/add-dedupe-consolidation` | New functionality (use `backlog-to-openspec`) | +| Fix | `fix/` | `fix/memory-leak-fix` | Bug fixes | +| Chore | `chore/` | `chore/update-skills-and-docs` | Infrastructure, tools, documentation, CI/CD | +| Release | `release/vX.Y.Z` | `release/v0.2.9` | Publishing to npm (use `release-workflow`) | + +--- + +### Choosing the Right Workflow + +Use **`backlog-to-openspec` → `feat/`** when: +- Implementing a new feature from the backlog +- Changes need specification documents +- Code and specs should stay synchronized + +Use **`chore/`** directly when: +- Updating skills (`.opencode/skills/`) +- Updating documentation (`.md` files) +- CI/CD configuration changes (`.github/`, `docker-compose.yml`) +- Build/tooling updates +- No new specification artifacts needed +- Changes are self-explanatory and don't need OpenSpec artifacts + +```bash +# Example: Updating skills documentation +git checkout -b chore/update-skills-and-docs +# ... make changes ... +git add . && git commit -m "chore: update skills and documentation" +git push origin chore/update-skills-and-docs -u +gh pr create --title "chore: update skills and documentation" --base main +``` + +--- + +### When to Use `backlog-to-openspec` vs. `chore/` + +| Aspect | backlog-to-openspec (`feat/`) | chore/ | +|--------|------------------------------|--------| +| **Purpose** | New features from backlog | Infrastructure/tools/docs | +| **Specification** | Generates OpenSpec artifacts | Not needed | +| **Branch** | `feat/` | `chore/` | +| **Testing** | Unit/integration/e2e required | Project-dependent | +| **Examples** | Add deduplication, new memory tool | Update skill docs, fix CI, add linter | + +If you're unsure, ask: "Does this need a specification document?" If no → use `chore/`. + +### File Locations + +| Purpose | Location | +|---------|----------| +| Backlog | `docs/backlog.md` | +| OpenSpec changes | `.opencode/changes//` | +| Release notes | `CHANGELOG.md` | +| Package config | `package.json` | + +--- + +## Troubleshooting + +### "Working tree is dirty" + +Either: +1. Stash changes: `git stash` +2. Commit changes: `git add . && git commit` + +### "Branch protection prevents push" + +Always use feature branches. See "Branch Naming Convention" above. + +### "CI checks failing" + +Check the specific failure: +```bash +gh run list --limit=5 +gh run view --log +``` + +### "npm publish failed" + +Common causes: +- `NPM_TOKEN` not set in GitHub Actions +- Version already exists +- TypeScript errors in build + +See `release-workflow` skill for detailed troubleshooting. + +--- + +## Related Documents + +- `README.md` — Project overview and installation +- `docs/backlog.md` — Current backlog items +- `docs/operations.md` — Operational procedures +- `docs/release-readiness.md` — Release criteria +- `.opencode/skills/backlog-to-openspec/SKILL.md` — Full skill documentation +- `.opencode/skills/release-workflow/SKILL.md` — Full skill documentation + +--- + +**Questions?** Open an issue or ask in the PR. diff --git a/docs/INDEX.md b/docs/INDEX.md index 21e36b6..e6ad83b 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -24,6 +24,14 @@ - Copy-paste examples - Time to read: 20 minutes (skim) / 1 hour (implement) +**🚀 New Contributor** +→ Start with: `DEVELOPMENT_WORKFLOW.md` +- How to use backlog-to-openspec and release-workflow skills +- Step-by-step development flow +- Branch naming conventions +- Quick reference commands +- Time to read: 10 minutes + **📋 Test Architect / QA Lead** → Start with: `memory-validation-checklist.md` - Complete specification @@ -42,6 +50,20 @@ ## 📄 Document Details +### 0.5. DEVELOPMENT_WORKFLOW.md (NEW) +**Purpose**: Development workflow & skill usage +**Best For**: New contributors, understanding the development process +**Contains**: +- Overview of backlog-to-openspec and release-workflow skills +- Step-by-step development flow (6 phases) +- Branch naming conventions +- Quick reference commands +- Troubleshooting common issues + +**Read Time**: 10 minutes + +--- + ### 1. VALIDATION_README.md (346 lines) **Purpose**: Navigation & overview **Best For**: Understanding the big picture @@ -145,6 +167,12 @@ 4. validation-priority-summary.md (10 min) 5. Design test infrastructure (35 min) +### Path 5: New Contributor (30 min) +1. DEVELOPMENT_WORKFLOW.md (10 min) — Start here! +2. README.md (10 min) +3. github-migration.md (5 min) +4. Quick start: run `docker compose up` and verify (5 min) + --- ## 🔍 Finding Specific Information @@ -299,6 +327,7 @@ - `operations.md` - Operations guide & rollback criteria - `embedding-migration.md` - Embedding model switching guide (Ollama ↔ OpenAI) - `lancedb-upgrades.md` - LanceDB upgrade notes +- `DEVELOPMENT_WORKFLOW.md` - Development workflow using OpenCode skills ---