Plan Flow

Structured AI-assisted development workflows - discovery, planning, execution, code reviews, and testing

Security Scan

The skill's stated purpose (AI-assisted development) mostly matches its requirements (git, gh), but its runtime instructions contain inconsistencies and a quietly persistent 'ledger' that records project memory without clear consent — this creates a risk of unexpected automatic changes or sensitive information being written to the repo.

Purpose & Capability

Name and features align with requiring git and gh for repo and PR work. The skill's commands (setup, discovery, plan, execute, review, tests) reasonably map to those tools. However, the inclusion of a silent, always-active project ledger (persistent memory) is more than a simple workflow helper and expands the skill's scope beyond pure planning/execution.

Instruction Scope

SKILL.md instructs the agent to automatically run multi-step workflows, create and modify files (plans, contracts, code, test files), run builds, and 'silently' capture learnings to flow/ledger.md. There are contradictory rules across files (e.g., main doc: 'Never ask "Ready to create plan?" — just do it.' vs. flow/SKILL.md's mandatory checkpoints and create-plan's 'Do NOT auto-invoke /execute-plan'). The instructions grant broad discretion to read/write project files and perform build/commit-related actions — this can lead to unexpected code changes or recording of sensitive content without explicit, consistent consent.

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is written to disk by an installer. This is lower risk from an installation vector perspective.

Credentials

The skill declares no required environment variables, which is consistent with an instruction-only skill. However, the Configuration section recommends creating a .plan-flow.yml containing an anthropic_api_key (example shown) — storing API keys in a repo file is discouraged and not enforced/validated. The skill also requires gh authentication for PR review; that is expected but users should be aware of auth scopes granted to gh.

Persistence & Privilege

Although registry flags show always: false, the SKILL.md explicitly documents an 'Always-Active Feature' (Project Ledger) and ledger/SKILL.md states the ledger 'operates silently in the background' and will read/apply learnings and record new entries. That is inconsistent with the declared privileges and effectively gives the skill persistent, background write/read access to the repo. This combination (silent ledger + automatic workflow language + file creation) increases the chance of unwanted persistent changes or leaking repository-specific information into flow/ledger.md.

What to consider before installing

Key things to consider before installing: - Ledger behavior: The skill documents a persistent 'flow/ledger.md' that is updated silently and used to influence future behavior. Ask the author how ledger entries are controlled, whether sensitive content is filtered, and how to disable ledger recording. Prefer not to enable this on repositories that contain secrets or proprietary logic. - Autopilot / automated actions: The top-level SKILL.md encourages automated runs and even says 'Never ask "Ready to create plan?" — just do it.' but other files contain contradictory checkpoints. Confirm whether the agent will actually modify files, run builds, or make commits without explicit user approval. If you require explicit approval before changes, do not enable autopilot. - Storage of API keys: The README suggests creating .plan-flow.yml with an anthropic_api_key example. Do NOT commit API keys to the repo; instead store provider keys in a secure secret store or environment variables and add .plan-flow.yml to .gitignore. Ask the author for a secure configuration alternative. - GitHub CLI auth: review what gh auth scopes you grant. The skill requires gh for PR review; ensure the token/account used has minimal necessary scopes. - Test in an isolated repo: Try the skill in a disposable repository first to observe behavior (file writes, commits, whether ledger populates, autopilot actions). Verify no automatic commits or pushes occur unless you explicitly approve. - Clarify inconsistencies: The SKILL.md set contains contradictory rules about auto-chaining and when to pause. Ask the maintainer to clarify intended autopilot behavior and how to opt out of any background logging. If you are uncomfortable with a silent, persistent ledger or any automatic file-modifying behavior, do not install or enable autopilot until you have explicit controls (ability to opt out of ledger, disable autopilot by default, and require explicit consent before code changes or commits).

Plan-Flow: Structured AI-Assisted Development

A comprehensive skill set for AI-assisted software development with structured workflows and persistent project memory.

Available Commands

Command	Description
/setup	Analyze project and generate pattern files
/discovery	Create discovery document for requirements gathering
/create-plan	Create implementation plan with phases and complexity scores
/execute-plan	Execute plan phases with verification
/create-contract	Create integration contract from API docs
/review-code	Review local uncommitted changes
/review-pr	Review a Pull Request
/write-tests	Write tests to achieve coverage target
/flow	Toggle autopilot mode (auto-chains the full workflow)

Always-Active Features

Feature	Description
Project Ledger	Persistent learning journal at flow/ledger.md - silently captures mistakes, corrections, and project-specific knowledge across sessions

Recommended Workflow

Automated - runs without asking permission:

1. /setup           → Index project patterns (run once)
2. /discovery       → Gather requirements for a feature
3. /create-plan     → Create structured implementation plan (auto-runs after discovery)
4. /execute-plan    → Execute the plan phase by phase (auto-runs after plan)
5. /review-code     → Review changes before committing
6. Archive          → Move discovery + plan to flow/archive/

Only stop to ask the user when:

• Missing critical information (device type, browser, etc.)
• Need to reproduce an issue
• Ambiguous requirements
• Need approval for destructive actions

Never ask "Ready to create plan?" or "Proceed with execution?" - just do it.

Core Concepts

Complexity Scoring

Every plan phase has a complexity score (0-10):

Score	Level	Description
0-2	Trivial	Simple, mechanical changes
3-4	Low	Straightforward implementation
5-6	Medium	Moderate complexity, some decisions
7-8	High	Complex, multiple considerations
9-10	Very High	Significant complexity/risk

Flow Directory Structure

All artifacts are stored in flow/:

flow/
├── archive/           # Completed/abandoned plans
├── contracts/         # Integration contracts
├── discovery/         # Discovery documents
├── plans/             # Active implementation plans
├── references/        # Reference materials
├── reviewed-code/     # Code review documents
├── reviewed-pr/       # PR review documents
└── ledger.md          # Persistent project learning journal

Critical Rules

1. Automated Workflow: Run discovery → plan → execute automatically. Only stop to ask when you need information from the user.
2. Discovery First (Hard Block): /discovery is required before /create-plan. Plans cannot be created without a discovery document. No exceptions. If no discovery exists, run discovery first.
3. Tests Last: Tests are always the last phase of any implementation plan.
4. Build at End Only: Run build verification only after ALL phases complete.
5. Archive When Done: Move completed discovery and plans to flow/archive/.

Configuration

Create .plan-flow.yml in your project root:

ai:
  provider: claude
  anthropic_api_key: sk-ant-api03-your-key-here

Requirements

• git - For version control operations
• gh - GitHub CLI for PR reviews

Installation

clawhub install plan-flow

Or add to your workspace skills folder:

git clone https://github.com/brunoscardoso/plan-flow.git ~/.openclaw/skills/plan-flow