refrakt.md

Docs Runes Plan Blog Changelog

Plan Workflows

@refrakt-md/plan is designed for spec-driven development — write specifications first, break them into trackable work items, and let the plan guide implementation. This workflow is particularly effective with AI coding assistants.

AI-assisted development

Setting up AI tool integration

When you run refrakt plan init, it generates a plan/INSTRUCTIONS.md file with the full workflow guide and appends a short reference to your AI tool's instruction file.

The --agent flag controls which instruction file gets updated:

refrakt plan init                    # auto-detect existing instruction files
refrakt plan init --agent claude     # append to CLAUDE.md
refrakt plan init --agent cursor     # append to .cursorrules
refrakt plan init --agent copilot    # append to .github/copilot-instructions.md
refrakt plan init --agent windsurf   # append to .windsurfrules
refrakt plan init --agent cline      # append to .clinerules
refrakt plan init --agent none       # skip instruction file update

When no --agent flag is provided, plan init auto-detects which instruction files already exist in your project and appends to all of them. If none are found, it falls back to creating a CLAUDE.md.

How it works with AI assistants

  1. Discovery — The assistant runs refrakt plan next to find the highest-priority actionable item
  2. Context — It reads the work item's file, follows references to specs in plan/specs/, and checks related decisions in plan/decisions/
  3. Implementation — It implements the changes, checking off acceptance criteria as each one is met
  4. Completion — When all criteria pass, it marks the item done and can move to the next

The --format json flag on all commands makes it easy for AI tools to parse output programmatically.

Custom instructions

You can add plan-specific instructions to plan/INSTRUCTIONS.md. This file is generated by plan init and includes:

  • ID naming conventions (e.g., WORK-XXX, SPEC-XXX, ADR-XXX)
  • Valid status flows for each entity type
  • Required content structure for specs, work items, and decisions
  • CLI command reference

Team workflows

Spec-first development

  1. Write a spec in plan/specs/ describing what to build
  2. Get the spec reviewed and accepted (refrakt plan update SPEC-001 --status accepted)
  3. Break the spec into work items in plan/work/, each referencing the spec
  4. Assign milestones and priorities
  5. Team members pick items with refrakt plan next --assignee me

Code review integration

Run refrakt plan validate in CI to catch:

  • Broken references between entities
  • Duplicate IDs
  • Invalid status or priority values
  • Circular dependencies
  • Orphaned work items without milestones
# In your CI pipeline
refrakt plan validate --strict

With --strict, warnings (like missing milestones) become errors that fail the build.

Milestone tracking

Group work items under milestones to track release progress:

# See overall status
refrakt plan status --milestone v1.0

# Find remaining work for a milestone
refrakt plan next --milestone v1.0 --count 10

The plan-progress and plan-activity runes render these views in your documentation site.

Plan dashboard

For a visual overview, use the built-in dashboard:

# Development mode with hot reload
refrakt plan serve --open

# Static build for hosting
refrakt plan build --out dist/plan

The dashboard renders all your plan entities as browsable pages with status indicators, cross-references, and progress tracking.