forte-spec

Forte-Spec is a Pi-native plugin that brings OpenSpec + Superpowers + Personas together into a single spec-driven development workflow.

It combines:

• OpenSpec for specifications, change management, artifacts, and workflow governance
• Superpowers for disciplined implementation, TDD, code review, and subagent-driven development
• Forte for the integrated workflow and custom OpenSpec schema
• Personas for role-based engineering perspectives
• Pi as the runtime and plugin platform

No separate installation of OpenSpec, Superpowers, or Personas is required.

Installation

pi install npm:forte-spec

Initialize a Project

Run Forte-Spec inside your project:

/forte-init

This initializes the Forte-Spec project structure:

openspec/
├── config.yaml
├── specs/
├── changes/
└── schemas/
    └── forte/
        ├── schema.yaml
        ├── templates/
        │   ├── brainstorm.md
        │   ├── proposal.md
        │   ├── design.md
        │   ├── spec.md
        │   ├── tasks.md
        │   ├── plan.md
        │   ├── apply.md
        │   ├── verify.md
        │   └── finalize.md
        ├── README.md
        └── INTEGRATION.md

The project uses the forte OpenSpec schema.

Start a Change

Create a new OpenSpec change:

/forte-new <change-name>

For example:

/forte-new refactor-alert-dialog

You can also explore an idea before creating a change:

/forte-explore

Or reuse a previously captured engineering discovery:

/forte-discovery

Discoveries are stored under:

.forte/discoveries/

A discovery is an optional engineering journal entry for an insight that is worth preserving but is not part of the current change scope.

A selected discovery provides context for the next /forte-new workflow. It does not become a requirement automatically and must be independently validated during change exploration.

Workflow

Forte-Spec follows a structured change lifecycle:

explore
   ↓
discover
   ↓
brainstorm
   ↓
proposal
   ↓
design (optional)
   ↓
specs
   ↓
tasks
   ↓
plan
   ↓
apply
   ↓
verify
   ↓
finalize
   ↓
archive

Step-by-step

/forte-new my-feature

Then advance through the artifacts:

/forte-continue    # brainstorm
/forte-continue    # proposal
/forte-continue    # design (optional)
/forte-continue    # specs
/forte-continue    # tasks
/forte-continue    # plan

Implement:

/forte-apply

Verify:

/forte-verify

Finalize:

/forte-continue

Archive:

/forte-archive

Git Branching

Forte-Spec uses an isolated Git workflow for implementation.

A dedicated feature branch is required before /forte-apply can begin.

The canonical flow is:

feature branch
      │
      ▼
OpenSpec artifacts committed
      │
      ▼
implementation worktree
      │
      ▼
worktree branch
      │
      ▼
implementation
      │
      ▼
verification
      │
      ▼
finalize
      │
      ▼
merge worktree branch
      │
      ▼
feature branch
      │
      ▼
push

If /forte-apply is started on main or master, Forte stops before committing artifacts or creating the worktree and asks whether it should create a feature branch.

Forte does not silently implement a change directly on the integration branch.

Detached HEAD is also not a valid starting state for the canonical apply workflow.

Apply and Implementation

/forte-apply creates an isolated implementation worktree and executes the implementation plan using Superpowers.

On platforms with subagent support, Forte uses:

superpowers:subagent-driven-development

This provides:

• task-by-task execution
• test-driven development
• code review after tasks
• fresh subagents for implementation tasks
• final implementation review

The implementation happens inside the dedicated worktree. The worktree branch is separate from the feature branch.

Verification

Run:

/forte-verify

Verification checks the implementation against the OpenSpec change artifacts.

It checks:

1. OpenSpec structural validity
2. Task completion
3. Delta spec synchronization state
4. Design/spec coherence
5. Git cleanliness and implementation commits

Possible outcomes:

PASS
PASS_WITH_WARNINGS
FAIL

A failed verification can return the workflow to /forte-apply for another implementation iteration.

Finalize

After verification passes:

/forte-continue

Forte enters the finalize phase.

The canonical flow is:

implementation worktree
        │
        ▼
verify tests
        │
        ▼
merge worktree branch
        │
        ▼
feature branch
        │
        ▼
push
        │
        ▼
optional PR

If a pull request already exists, pushing the feature branch updates it.

If no PR exists, Forte can offer to create one after finalization.

For non-canonical situations, the bundled superpowers:finishing-a-development-branch skill remains available as a manual escape hatch.

Archive

Once finalize.md exists:

/forte-archive

The completed change can be archived and the relevant specifications synchronized.

Personas

Forte-Spec provides role-based engineering perspectives:

/forte-persona architect
/forte-persona developer
/forte-persona tester
/forte-persona reviewer
/forte-persona security
/forte-persona debugger

Clear the active persona:

/forte-persona off

Show the current persona:

/forte-persona

Personas are session-scoped.

| Phase | Personas | | ---------- | ----------------------------- | | brainstorm | architect, security | | proposal | architect | | design | architect, security, reviewer | | specs | developer, tester, reviewer | | tasks | architect, developer | | plan | architect, developer | | apply | developer, tester | | verify | tester, security, reviewer | | finalize | reviewer | | archive | reviewer |

The mapping can be configured in the project's Forte configuration.

Explore vs. Change

Forte-Spec separates freeform exploration from change-oriented execution.

Explore

/forte-explore

Use this to investigate a problem, understand the codebase, or think through an idea without immediately creating an OpenSpec change.

Discovery

/forte-discovery

Use this to browse previously captured engineering insights.

Discoveries are persistent notes, not requirements. They can capture:

• architectural observations
• possible refactoring opportunities
• reusable component candidates
• technical debt observations
• ideas discovered while implementing another change

A discovery only becomes relevant to a new change when explicitly selected.

Change

/forte-new <change-name>

Use this when an idea is ready to become a governed OpenSpec change.

Grill Me

For designs that need rigorous questioning, use the bundled grill-me skill.

It can challenge a design by:

• questioning assumptions
• identifying missing requirements
• exposing edge cases
• examining architectural trade-offs
• exploring the codebase where useful
• suggesting stronger answers

Architecture

| Layer | Responsibility | | --------------- | ----------------------------------------------------------------------- | | OpenSpec | Specification, change management, artifacts, and workflow governance | | Superpowers | Execution discipline, TDD, code review, and subagent-driven development | | Forte | Custom workflow and OpenSpec schema integration | | Personas | Role and perspective context | | Pi | Runtime and plugin platform |

The key separation is:

OpenSpec      → WHAT should change
Superpowers   → HOW the change is implemented
Forte         → HOW these systems are integrated into one workflow
Personas      → WHO is looking at the problem
Pi            → WHERE the workflow runs

Bundled Skills

Forte-Spec bundles:

brainstorming
writing-plans
test-driven-development
systematic-debugging
subagent-driven-development
requesting-code-review
using-git-worktrees
executing-plans
finishing-a-development-branch
using-superpowers
grill-me

Design Principles

Specification before implementation

Implementation is driven by explicit requirements and scenarios rather than an ad-hoc coding session.

Small, reviewable changes

Each OpenSpec change represents a focused unit of work with its own artifacts, implementation plan, verification, and Git lifecycle.

Isolated implementation

Implementation takes place in a dedicated Git worktree rather than directly in the main checkout.

Explicit scope

Discoveries and ideas encountered during implementation do not silently expand the current change.

Evidence over assumptions

Verification, code review, and implementation receipts provide evidence that the implementation corresponds to the intended change.

Human control

Forte automates workflow mechanics while keeping scope and branch decisions explicit.

Credits

Forte-Spec is inspired by:

• SuperSpec by Daniel Hanold — the original integration of OpenSpec governance with Superpowers execution, demonstrating the schema-as-plugin model.
• OpenSpec by Fission AI — the specification framework and orchestration foundation for versioned, reviewable specs.

Forte-Spec builds on these ideas to provide a Pi-native, drop-in experience.

References

• Forte-Spec: fortezhuo/forte-spec
• Superpowers: obra/superpowers
• OpenSpec: @fission-ai/openspec

License

MIT — see LICENSE.