@supierior/feature-workflow

Pi Workflower package for turning feature conversations into feature docs, reviewed implementation plans, split story files, and reviewed story-by-story implementations.

It registers three user-facing workflows:

new-feature
take-it-away
feature-doc

It also registers private loop workflows used through workflower_handoff:

implementation-doc-loop
implementation-stories-split
story-implementation-loop

All feature-workflow skills are private Workflower skills exposed through pi.workflowerSkills.

User-facing workflows

new-feature

Use when starting from a new idea. The workflow clears context on start and always grills the user first.

Steps:

1. grill — /skill:feature-grill
   • clarifies the feature through focused questioning;
   • writes no files;
   • user runs /next when alignment is reached.
2. create-feature-doc — /skill:feature-doc-create, writes feature-doc.md
   • converts the grill conversation into an intermediate feature document;
   • saves featureDocPath in Workflower garden state;
   • pins feature-doc.md as pollen.
3. start-implementation-doc-loop — private router command
   • reads garden state and asks the model to call workflower_handoff for implementation-doc-loop.

take-it-away

Use after an organic conversation with Pi. The workflow preserves the current conversation on start, creates a feature doc first, then enters the same implementation flow as new-feature.

Runtime profile:

• defaults to openai/gpt-5.4-mini with low thinking for quick workflow movement;
• keeps feature-doc creation at medium thinking;
• hands implementation planning to a higher-thinking step in implementation-doc-loop;
• keeps review steps at medium thinking and router steps at minimal thinking.

Steps:

1. create-feature-doc — /skill:feature-doc-create, writes feature-doc.md and saves featureDocPath.
2. start-implementation-doc-loop — private router command to hand off to implementation-doc-loop.

feature-doc

Use when you only want a durable feature document from the current conversation.

Steps:

1. create-feature-doc — /skill:feature-doc-create, writes feature-doc.md and saves featureDocPath.

This workflow does not clean up its workdir on completion, so the generated document remains in .workflower/workflows/<garden>/0001-feature-doc/.

Private loop workflows

implementation-doc-loop

Creates or improves implementation-doc.md, reviews it, and routes based on garden state.

Runtime profile:

• workflow default: openai/gpt-5.4-mini with low thinking;

• planning step override: openai/gpt-5.5 fallback to openai/gpt-5.4-mini, with high thinking;

• review step override: medium thinking;

• router step override: minimal thinking.

• Passing review score: >= 4 on a 1-5 scale.

• Maximum improvement attempts: 5.

• Review facts are saved under implementationDocReview.

• The router mutates implementationDocReviewAttempts and loops through workflower_handoff when review fails.

• On success, it hands off to implementation-stories-split.

implementation-stories-split

Splits an accepted implementation doc into topologically ordered story files under stories/ and saves storyManifest plus the first currentStory routing state.

Runtime profile:

• workflow default: openai/gpt-5.4-mini with low thinking;
• story-splitting step override: medium thinking;
• router step override: minimal thinking.

Story files are implementation-ready and written as instructions to a junior developer.

story-implementation-loop

Implements one story, reviews it, and routes based on garden state.

Runtime profile:

• workflow default: openai/gpt-5.4-mini with low thinking;

• implementation step stays low thinking on the fast model;

• review step is raised to medium thinking;

• router step stays minimal.

• Passing review score: >= 4 on a 1-5 scale.

• Maximum improvement attempts per story: 3.

• Review facts are saved under storyReview.

• On failure, the router hands off to another loop iteration for the same story.

• On success, the router advances currentStory to the next story.

• When all stories pass, the router reports completion and does not hand off.

Context management

The architecture keeps creation and review context small:

• large artifacts live in files, not garden state;
• reviewer skills save compact structured ratings and required improvements in garden state;
• private router commands read garden state and emit only the next routing instruction;
• loop continuation uses workflower_handoff, not printed slash commands;
• workflow steps clear context between create/review/router phases where possible.

Router commands intentionally act as deterministic script steps for loop decisions, while creator skills receive only the current artifact plus concise state feedback.

Garden state keys

Core keys:

featureDocPath
implementationDocPath
implementationDocReview
implementationDocReviewAttempts
implementationDocStatus
storyManifest
currentStoryIndex
currentStory
storyReview
storyReviewAttempts
storyReviewStatus
featureWorkflowStatus

Reviewer object shape (score >= 4 passes):

{
  "score": 4,
  "summary": "Short reason for the score.",
  "methodologyRatings": {
    "tdd": 4,
    "verticalSlicing": 4,
    "tracerBullet": 4,
    "dependencies": 4,
    "architecture": 4
  },
  "requiredImprovements": [],
  "reviewedPath": "/absolute/path/to/file.md"
}

Smoke tests

Start from scratch:

/wf:new-feature demo

After the grill reaches alignment:

/next

Use an existing conversation:

/wf:take-it-away demo

Generate only a feature doc:

/wf:feature-doc demo

Useful Workflower inspection:

/wf status
/wf state list
/wf state get implementationDocReview
/wf state get storyManifest