devflow-kit 1.8.3 → 2.0.1

package/dist/commands/release.md

@@ -0,0 +1,206 @@
+---
+description: Release project using adaptive learned configuration
+---
+
+# Release Command
+
+Release the project using adaptive learned configuration. On first run, scans the codebase to detect the release process and stores it in `.release/RELEASE-FLOW.md`. Subsequent releases use the stored config, skipping discovery.
+
+## Usage
+
+```
+/release v1.2.3          (explicit version)
+/release patch           (bump type: patch | minor | major)
+/release --dry-run       (simulate release, show plan without executing)
+/release                 (interactive: ask for version)
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/release`:
+- Explicit version: `v1.2.3` or `1.2.3`
+- Bump type: `patch`, `minor`, `major`
+- Flag: `--dry-run`
+- Empty: interactive mode (will ask for version)
+
+Parse from $ARGUMENTS:
+- `VERSION`: explicit version string if present (strip leading `v`)
+- `BUMP_TYPE`: `patch | minor | major` if bump type provided
+- `DRY_RUN`: true if `--dry-run` present, false otherwise
+
+## Phases
+
+### Phase 1: Load Config
+
+**Produces:** RELEASE_CONFIG, CONFIG_STATE (`learned` | `fresh`)
+
+**Load Companion Skills** — Load via Skill tool: `devflow:git`. If a skill fails to load, continue without it.
+
+**Continuation detection**: Check `.release/.progress.json`. If exists, an interrupted release is in progress. Offer user:
+- **Resume**: continue from last checkpoint (skip phases already completed)
+- **Restart**: clean start (delete `.release/.progress.json` and begin from Phase 1)
+
+Read `.release/RELEASE-FLOW.md`:
+- If exists → parse as structured config, set CONFIG_STATE = learned, skip to Phase 4
+- If missing → set CONFIG_STATE = fresh, continue to Phase 2
+
+### Phase 1b: Load Context
+
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+
+Read `.devflow/learning/index.md`. If the file is absent or empty, set `DECISIONS_CONTEXT` to `(none)`; otherwise use the file content as `DECISIONS_CONTEXT`.
+
+Load feature knowledge: Attempt to read `.devflow/features/index.md` (the regenerable cache). If absent or empty, glob `.devflow/features/*/KNOWLEDGE.md` and read each file's YAML frontmatter (`name`, `description`, `directories`) as the relevance surface. Pick release-relevant KBs by matching their documented area against the release context. For each selected KB, read the full `KNOWLEDGE.md` — trust current code over KB content on any mismatch. Concatenate under slug headers and set `FEATURE_KNOWLEDGE` (or `(none)` if no KBs exist or none are relevant). No `index.json`, no subprocess, no `.cjs` script.
+
+Pass both to all subsequent agents via their input contracts.
+
+### Phase 1c: Resolve Compliance Context
+
+**Produces:** COMPLIANCE_SKILL_INSTALLED
+
+**Resolve `COMPLIANCE_SKILL_INSTALLED` once per run:** Check whether `~/.claude/skills/devflow:compliance/SKILL.md` exists (one file-existence check, read-only, silent). Set `COMPLIANCE_SKILL_INSTALLED = true` if the file exists, `false` otherwise. Reuse this result for all subsequent phases. The compliance gate determines whether release evidence is gathered and shipped-issue back-links are posted.
+
+### Phase 2: Detect Release Process (First Run Only)
+
+**Produces:** RELEASE_SIGNALS
+**Requires:** CONFIG_STATE = fresh
+
+Tiered codebase scan to detect the project's release process:
+
+**Tier 1** — Read these if they exist: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Dockerfile`, `.github/workflows/*.yml`, `CHANGELOG.md`
+
+**Tier 2** — Broaden: monorepo indicators (`lerna.json`, `pnpm-workspace.yaml`, `turbo.json`), release tool configs (`.releaserc`, `.changeset/`, `release-please-config.json`)
+
+**Tier 3** — Git history: `git tag -l` for tag format, `git log --oneline -20` for conventions
+
+Skip credential files (`.env*`, `*credentials*`, `*secret*`, `*.key`). Max 20 files total.
+
+### Phase 3: Build Config (First Run Only)
+
+**Produces:** RELEASE_CONFIG (written to disk)
+**Requires:** RELEASE_SIGNALS
+
+Map RELEASE_SIGNALS to `.release/RELEASE-FLOW.md` with sections: Packages, Pre-release Checks, Changelog, Build & Test, Publish, Post-release.
+
+**Conventions naming:** Consult `.devflow/conventions.md` (the naming authority written by the Git `learn-conventions` operation) for version/tag/version-PR title conventions. When the branching model uses version PRs, follow the Version PR Titles convention recorded there; compliance defaults when the file is absent. When the repo uses a main+integration branching model, ship via a version PR per the recorded convention. Re-learn by deleting `.devflow/conventions.md` — the next Git `learn-conventions` call rewrites it.
+
+Use AskUserQuestion for any gaps that cannot be inferred.
+
+Lazy-init `.release/` directory. Create `.release/.gitignore` with `.progress.json` and `.lock/`.
+
+### Phase 4: Pre-release Checks
+
+**Produces:** PRE_RELEASE_RESULT, VERSION
+**Requires:** RELEASE_CONFIG
+
+**Version determination** (in order):
+1. Explicit version from args → use directly
+2. Bump type from args → compute from current version
+3. `semver-auto` strategy → analyze commits since last tag
+4. None → use AskUserQuestion
+
+Pre-release checks:
+- Clean working directory (`git status --porcelain`)
+- Tag does not already exist
+- Custom checks from RELEASE_CONFIG
+
+Spawn `Agent(subagent_type="Validate")` for build + test.
+
+Write `.release/.progress.json` checkpoint.
+
+`--dry-run`: report what would happen and **halt after this phase**.
+
+### Phase 5: Build Release Plan
+
+**Produces:** RELEASE_PLAN
+**Requires:** PRE_RELEASE_RESULT, RELEASE_CONFIG, VERSION
+
+Build ordered execution plan from RELEASE_CONFIG. For monorepo: respect dependency ordering, present package selection to user.
+
+Confirm with user via AskUserQuestion before executing:
+"Ready to release v{VERSION}. Plan: {steps summary}. Proceed?"
+
+`--dry-run`: should already be halted from Phase 4.
+
+### Phase 6: Execute Release
+
+**Produces:** RELEASE_RESULT
+**Requires:** RELEASE_PLAN, VERSION
+
+Sequential execution with progress checkpoints:
+1. **Version bumps** — write new version to configured files
+2. **Changelog update** — move Unreleased section to versioned entry (if configured)
+2b. **Gather release evidence** (compliance-gated: only when COMPLIANCE_SKILL_INSTALLED) — spawn `Agent(subagent_type="Git")` with `gather-release-evidence` operation; pass `WORKTREE_PATH` if provided. Consume the returned `COMMIT_LIST` and `SHIPPED_ISSUES` for use in steps 4 and 4b. The Git agent applies bounds (≤100 commits, ≤50 issues) and degrades gracefully per D4.
+3. **Release commit** — `chore(release): v{VERSION}` (conventional commit)
+4. **Tag and GitHub Release** — spawn `Agent(subagent_type="Git")` with `create-release` operation (the agent reads `.devflow/conventions.md` for tag format and release title conventions; compliance defaults when absent); when COMPLIANCE_SKILL_INSTALLED, also pass `COMMIT_LIST` and `SHIPPED_ISSUES` as inputs so the agent includes them in the release notes body.
+4b. **Back-link shipped issues** (compliance-gated: only when COMPLIANCE_SKILL_INSTALLED) — spawn `Agent(subagent_type="Git")` with `backlink-shipped-issues` operation, passing `VERSION` and `SHIPPED_ISSUES`; posts a marker-deduped comment on each issue (bounds and throttle enforced by the operation); degrade gracefully (D4) on any API failure — never block the release
+5. **Publish** — CI-driven (report) or manual (provide instructions)
+6. **Post-release steps** — version bump to next dev, close milestone, etc.
+
+Delete `.release/.progress.json` on success.
+
+### Phase 7: Suggest Improvements
+
+**Requires:** RELEASE_RESULT
+
+Post-release analysis for improvement opportunities. Present as suggested diffs to RELEASE-FLOW.md. Never auto-apply. Fire-and-forget.
+
+## Worktree Support
+
+If the orchestrator receives a `WORKTREE_PATH` context, pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution.
+
+## Output
+
+On completion:
+- Git tag created: `v{VERSION}` (or configured tag format)
+- GitHub Release created with release notes
+- Changelog updated (if configured)
+- Version files bumped
+- `.release/RELEASE-FLOW.md` created (first run only)
+
+## Architecture
+
+```
+/release (orchestrator)
+│
+├─ Phase 1: Load Config
+│  └─ Read .release/RELEASE-FLOW.md (learned) or proceed to detect (fresh)
+│
+├─ Phase 1b: Load Context
+│  └─ Load DECISIONS_CONTEXT and FEATURE_KNOWLEDGE for downstream agents
+│
+├─ Phase 2: Detect Release Process (first run only)
+│  └─ Tiered scan: package.json, CI workflows, git history
+│
+├─ Phase 3: Build Config (first run only)
+│  └─ Write .release/RELEASE-FLOW.md
+│
+├─ Phase 4: Pre-release Checks
+│  ├─ Validate agent (build + test)
+│  └─ Write progress checkpoint
+│
+├─ Phase 5: Build Release Plan
+│  └─ Confirm with user before executing
+│
+├─ Phase 6: Execute Release
+│  ├─ Version bumps → Changelog → Commit → Git agent (tag + release) → Publish → Post-release
+│  └─ Progress checkpoints between each step
+│
+└─ Phase 7: Suggest Improvements
+   └─ Suggested diffs to RELEASE-FLOW.md (never auto-applied)
+```
+
+## Principles
+
+1. **Learn once, reuse always** — discovery happens on first run; subsequent releases skip it
+2. **Config is data, not code** — structured config fields map to pre-defined operations, never raw shell commands
+3. **Checkpoint-resume** — progress file enables safe resume of interrupted releases
+4. **User confirms before execution** — release plan is presented for approval before any tags or commits
+
+## Error Handling
+
+- Validate agent fails (build/test): halt, report failures, do not proceed
+- User declines release plan: halt gracefully
+- Git agent fails (tag/release): halt, report error, suggest manual steps
+- Mid-release failure: progress checkpoint enables resume on next run
+- Version file not found: halt, report which file is missing, ask user to update RELEASE-FLOW.md

package/dist/commands/research.md

@@ -0,0 +1,212 @@
+---
+description: Research a topic using parallel multi-type Research agents with trust-aware synthesis
+---
+# Research Command
+
+Research a topic by spawning parallel Research agents across multiple research types (codebase, external, market, competitor, technology). Findings are trust-annotated and synthesized into structured output.
+
+## Usage
+
+```
+/research "best caching strategies"
+/research "compare React vs Svelte for our use case"
+/research "what open-source competitors exist"
+/research "how does our auth system work and what are the industry alternatives"
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/research`:
+- Research question: "best caching strategies"
+- Comparison question: "compare React vs Svelte for our use case"
+- Empty: use conversation context
+
+## Phases
+
+### Phase 1: Load Decisions (Orchestrator-Local)
+
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+
+### Load DECISIONS_CONTEXT
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the pre-rendered index:**
+
+Attempt to read `{worktree}/.devflow/learning/index.md`.
+
+- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
+- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+
+**No subprocess, no `.cjs` script.** This is a single direct file read — the index is written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md`.
+
+**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+
+When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+
+Use `DECISIONS_CONTEXT` locally when framing research — prior decisions and pitfalls suggest areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. Pass `DECISIONS_CONTEXT` to each Research agent in Phase 4 so they can cite relevant decisions in findings.
+
+### Load Feature Knowledge
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the index cache:**
+
+Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
+
+```
+- **{slug}** — {areas} — {Use-when description}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+
+**Step 3 — Pick relevant KBs:**
+
+Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+
+**Step 4 — Read selected KBs:**
+
+For each selected entry, read `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+
+**Step 5 — Set FEATURE_KNOWLEDGE:**
+
+Concatenate the selected KNOWLEDGE.md files under slug headers:
+
+```
+--- Feature knowledge: {slug} ---
+{full KNOWLEDGE.md content}
+```
+
+If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+
+**No subprocess, no git calls, no `.cjs` script.** This entire step is direct file reads — 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+
+Use `FEATURE_KNOWLEDGE` **locally** for research framing. Pass to each Research agent in Phase 4.
+
+### Phase 2: Requirements
+
+**Produces:** RESEARCH_PLAN
+
+Analyze the research question to infer research types needed (min 2, max 5). For each type:
+- `RESEARCH_TYPE`: `codebase | external | market | competitor | technology`
+- `RESEARCH_QUESTION`: Focused sub-question for this type
+- `OUTPUT_PATH`: `.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}/{type}.md`
+
+**Tool availability check**: If WebSearch/WebFetch are unavailable, restrict to `codebase` type only.
+
+Generate topic slug from the research question (kebab-case, lowercase, no articles).
+
+### Phase 3: Orient (Conditional)
+
+**Produces:** ORIENT_OUTPUT
+
+Only if `codebase` type is in RESEARCH_PLAN.
+
+Spawn `Agent(subagent_type="Skim")` targeting codebase areas relevant to the research question.
+
+Skip and set ORIENT_OUTPUT = "(none)" if `codebase` type is not in RESEARCH_PLAN.
+
+### Phase 4: Parallel Research agents
+
+**Produces:** RESEARCH_OUTPUTS
+**Requires:** RESEARCH_PLAN, ORIENT_OUTPUT (optional)
+
+Spawn 2-5 `Agent(subagent_type="Research")` agents **in a single message** (parallel execution).
+
+Each Research agent receives:
+- `RESEARCH_TYPE`, `RESEARCH_QUESTION`, `OUTPUT_PATH` from RESEARCH_PLAN
+- `DECISIONS_CONTEXT`: From Phase 1
+- `FEATURE_KNOWLEDGE`: From Phase 1
+- `ORIENT_OUTPUT`: Only for `codebase` type
+- `WORKTREE_PATH`: If in a worktree context
+
+Each Research agent writes findings to disk at OUTPUT_PATH.
+
+### Phase 5: Synthesize
+
+**Produces:** RESEARCH_SUMMARY
+**Requires:** RESEARCH_OUTPUTS
+
+Spawn `Agent(subagent_type="Synthesize")` in `research` mode:
+- Reads Research agent outputs from RESEARCH_OUTPUTS paths
+- Merges findings with trust-aware aggregation
+- Writes `research-summary.md` to the same timestamped directory
+
+Output path: `.devflow/docs/research/{topic-slug}/{timestamp}/research-summary.md`
+
+### Phase 6: Present
+
+**Requires:** RESEARCH_SUMMARY
+
+Present findings to user with:
+- Trust annotations per finding: (trusted) for codebase, (untrusted) for web, (mixed) for technology
+- Explicit conflicts between codebase and web findings
+- Drill-down offer via AskUserQuestion
+
+If external research was skipped due to tool unavailability: inform user.
+
+### Phase 7: Feature Knowledge Creation (Conditional)
+
+**Requires:** RESEARCH_SUMMARY, DECISIONS_CONTEXT
+**Produces:** FEATURE_KNOWLEDGE_STATUS (created | skipped)
+
+1. If `codebase` type was not in RESEARCH_PLAN → skip
+2. Check if matching feature knowledge already exists by reading `{worktree}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
+3. Use AskUserQuestion: "No feature knowledge exists for {researched area}. Create one?"
+4. If user accepts: spawn `Agent(subagent_type="Knowledge")` with researched area context + worktree root, instructing it to load `devflow:feature-knowledge`, write `KNOWLEDGE.md`, and update `index.md` directly
+5. Set FEATURE_KNOWLEDGE_STATUS = created or skipped
+
+**Failure handling**: Non-blocking. If Knowledge agent fails, log and continue.
+
+## Worktree Support
+
+If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktree workflows), pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution.
+
+## Output
+
+Research findings saved to `.devflow/docs/research/{topic-slug}/{YYYY-MM-DD_HHMM}/`:
+- `{type}.md` per research type (codebase.md, external.md, etc.)
+- `research-summary.md` — synthesized findings with trust annotations
+
+## Architecture
+
+```
+/research (orchestrator)
+│
+├─ Phase 1: Load Decisions (Orchestrator-Local)
+│
+├─ Phase 2: Requirements
+│  └─ Infer 2-5 research types from question
+│
+├─ Phase 3: Orient (conditional — codebase type only)
+│  └─ Skim agent (codebase overview)
+│
+├─ Phase 4: Parallel Research agents
+│  └─ 2-5 Research agents in single message (all types simultaneously)
+│
+├─ Phase 5: Synthesize
+│  └─ Synthesize agent merges findings with trust-aware aggregation
+│
+├─ Phase 6: Present findings with trust annotations and drill-down offer
+│
+└─ Phase 7: Suggest feature knowledge creation (conditional)
+   └─ Knowledge agent (if codebase type researched + user accepts)
+```
+
+## Principles
+
+1. **Parallel perspectives** — Multiple research types converge on truth better than any single perspective
+2. **Trust transparency** — Every finding is labeled with its trust level (trusted/untrusted/mixed)
+3. **Conflict surfacing** — Contradictions between codebase and web findings are highlighted, not hidden
+4. **Evidence over opinion** — All claims require citations (file:line or URL)
+
+## Error Handling
+
+- If WebSearch/WebFetch unavailable: restrict to codebase type, inform user
+- If a Research agent fails: continue with remaining outputs, note gap in synthesis
+- If Synthesize agent fails: present individual Research agent outputs directly
+- If feature knowledge creation fails: log failure, report research results normally