plan-flow-skill 1.0.0

package/rules/tools/reference-expansion-tool.mdc

@@ -0,0 +1,338 @@
+---
+description: "Tool for expanding reference codes to load full content on-demand"
+alwaysApply: false
+---
+
+# Reference Expansion Tool
+
+## Purpose
+
+This tool documents how to use the hierarchical context loading system with reference codes. Instead of loading full files, load the index first, then expand specific sections on-demand.
+
+---
+
+## Reference Code System
+
+### Code Prefixes
+
+| Prefix | Folder | Description |
+|--------|--------|-------------|
+| COR- | `rules/core/` | Core rules (allowed/forbidden patterns, complexity) |
+| LNG- | `rules/languages/` | Language-specific patterns |
+| PTN- | `rules/patterns/` | Pattern files (discovery, plans, tests, etc.) |
+| SKL- | `rules/skills/` | Skill files for commands |
+| TLS- | `rules/tools/` | Tool documentation |
+
+### Code Format
+
+```
+[PREFIX]-[SUBCATEGORY]-[NUMBER]
+```
+
+**Examples**:
+- `COR-1` - Core rule section 1
+- `LNG-TS-1` - TypeScript pattern section 1
+- `PTN-DIS-1` - Discovery pattern section 1
+- `SKL-EXEC-1` - Execute plan skill section 1
+- `TLS-AUTH-1` - Auth tool section 1
+
+---
+
+## Expansion Workflow
+
+### Step 1: Load the Index
+
+When a command or skill is invoked, load the relevant `_index.mdc` file:
+
+```
+rules/[folder]/_index.mdc
+```
+
+The index contains a table of all reference codes with descriptions.
+
+### Step 2: Identify Needed References
+
+Based on the current task, identify which reference codes are needed:
+
+- Read the "When to Expand" section in the index
+- Match the task to specific codes
+- Only expand what's needed for the current task
+
+### Step 3: Expand Reference Codes
+
+Use the Read tool to load the specific line range:
+
+```
+Read file: rules/[folder]/[filename].mdc
+Lines: [start]-[end]
+```
+
+### Step 4: Use the Content
+
+The expanded content is now in context. Use it for the current task.
+
+---
+
+## When to Expand vs. When to Skip
+
+### Expand When
+
+| Situation | Action |
+|-----------|--------|
+| Creating a discovery document | Expand PTN-DIS-* (discovery templates/patterns) |
+| Writing tests | Expand PTN-JEST-* or PTN-PYTEST-* |
+| Reviewing a PR | Expand PTN-PR-* and SKL-PR-* |
+| Need specific example code | Expand the example section code |
+| Following a specific pattern | Expand that pattern's section |
+
+### Skip When
+
+| Situation | Action |
+|-----------|--------|
+| Task is simple and familiar | Use index summary only |
+| Pattern is well-known | Don't expand, just reference |
+| Multiple sections might apply | Start with index, narrow down |
+| Already have similar context | Don't duplicate |
+
+---
+
+## Example: Discovery Command
+
+**Task**: Create a discovery document
+
+**Step 1**: Load index
+```
+Read: rules/patterns/_index.mdc
+```
+
+**Step 2**: Identify needed codes from index
+- PTN-DIS-1: Discovery document template
+- PTN-DIS-2: Requirements gathering example
+
+**Step 3**: Expand specific sections
+```
+Read: rules/patterns/discovery-templates.mdc
+Lines: 15-80  (for PTN-DIS-1)
+Lines: 244-279 (for PTN-DIS-2)
+```
+
+**Step 4**: Use templates to create the document
+
+---
+
+## Example: Execute Plan Command
+
+**Task**: Execute an implementation plan
+
+**Step 1**: Load indexes
+```
+Read: rules/skills/_index.mdc
+Read: rules/core/_index.mdc
+```
+
+**Step 2**: Identify needed codes
+- SKL-EXEC-1: Execution workflow
+- SKL-EXEC-2: Complexity-based grouping
+- COR-3: Complexity scoring table
+
+**Step 3**: Expand as needed during execution
+
+---
+
+## Maintenance Guidelines
+
+### When to Update Indexes
+
+Update the relevant `_index.mdc` when:
+
+1. **Adding a new section** to a source file
+2. **Removing a section** from a source file
+3. **Renaming a section** in a source file
+4. **Line numbers change** significantly (after major edits)
+
+### How to Update
+
+1. Open the source file and identify the new/changed section
+2. Note the line range (start line to end line)
+3. Update the `_index.mdc` reference table:
+   - Add new code for new sections
+   - Update line ranges for moved sections
+   - Remove codes for deleted sections
+
+### Best Practices
+
+| Practice | Reason |
+|----------|--------|
+| Update index immediately after editing source | Prevents stale references |
+| Use descriptive section descriptions | Helps identify correct code |
+| Keep line ranges accurate | Ensures correct content is loaded |
+| Review indexes periodically | Catch any drift |
+
+---
+
+## Index File Locations
+
+| Folder | Index Path |
+|--------|------------|
+| Core | `rules/core/_index.mdc` |
+| Languages | `rules/languages/_index.mdc` |
+| Patterns | `rules/patterns/_index.mdc` |
+| Skills | `rules/skills/_index.mdc` |
+| Tools | `rules/tools/_index.mdc` |
+
+---
+
+## Troubleshooting
+
+### Reference Code Not Found
+
+If a reference code isn't in the index:
+1. Check the prefix matches the correct folder
+2. Verify the index file exists
+3. The section may have been added recently - check source file
+
+### Line Range Invalid
+
+If the line range doesn't match expected content:
+1. The source file was edited after index creation
+2. Re-analyze the source file
+3. Update the line range in the index
+
+### Content Seems Incomplete
+
+If expanded content is missing context:
+1. Expand a larger line range
+2. Include surrounding sections
+3. Check if section references other sections
+
+---
+
+## Adding New Reference Codes
+
+When adding content to the project that should be indexed:
+
+### Step 1: Create or Edit the Source File
+
+Add your new section to the appropriate file in `rules/`:
+- Core rules → `rules/core/`
+- Language patterns → `rules/languages/`
+- Patterns → `rules/patterns/`
+- Skills → `rules/skills/`
+- Tools → `rules/tools/`
+
+### Step 2: Determine the Reference Code
+
+Use the naming convention:
+```
+[PREFIX]-[SUBCATEGORY]-[NUMBER]
+```
+
+| Prefix | For Files In |
+|--------|--------------|
+| COR- | rules/core/ |
+| LNG- | rules/languages/ |
+| PTN- | rules/patterns/ |
+| SKL- | rules/skills/ |
+| TLS- | rules/tools/ |
+
+### Step 3: Update the Index
+
+Open `rules/[folder]/_index.mdc` and add a new row to the reference table:
+
+```markdown
+| NEW-CODE-1 | 150-180 | Description of the new section |
+```
+
+### Step 4: Verify
+
+1. Check the line numbers match the actual content
+2. Ensure the description is clear and actionable
+3. Update "When to Expand" section if needed
+
+---
+
+## Context Savings Estimate
+
+The hierarchical loading system reduces context consumption significantly:
+
+### Before (Full Loading)
+
+| Folder | Total Lines | Always Loaded |
+|--------|-------------|---------------|
+| rules/core/ | ~1,200 | Yes (partial) |
+| rules/languages/ | ~800 | No |
+| rules/patterns/ | ~2,500 | No |
+| rules/skills/ | ~2,800 | No |
+| rules/tools/ | ~1,400 | No |
+| **Total** | **~8,700** | |
+
+### After (Index + On-Demand)
+
+| Component | Lines | When Loaded |
+|-----------|-------|-------------|
+| Index files (6 total) | ~600 | Per command |
+| Average expansion | ~100-200 | Per task |
+| **Typical session** | **~800-1,000** | |
+
+### Estimated Savings
+
+| Scenario | Before | After | Savings |
+|----------|--------|-------|---------|
+| Discovery command | ~3,500 lines | ~800 lines | ~77% |
+| Execute plan | ~4,000 lines | ~1,000 lines | ~75% |
+| Write tests | ~2,500 lines | ~600 lines | ~76% |
+| **Average** | **~3,300 lines** | **~800 lines** | **~76%** |
+
+---
+
+## System Overview
+
+The context optimization system consists of:
+
+### Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| Index Template | `rules/templates/index-template.mdc` | Template for creating new indexes |
+| Core Index | `rules/core/_index.mdc` | Core rules reference codes |
+| Languages Index | `rules/languages/_index.mdc` | Language patterns reference codes |
+| Patterns Index | `rules/patterns/_index.mdc` | Pattern files reference codes |
+| Skills Index | `rules/skills/_index.mdc` | Skill files reference codes |
+| Tools Index | `rules/tools/_index.mdc` | Tool files reference codes |
+| Expansion Tool | `rules/tools/reference-expansion-tool.mdc` | This documentation |
+
+### Workflow Summary
+
+```
+Command Invoked
+      |
+      v
+Load Command File
+      |
+      v
+Load Relevant Indexes (_index.mdc)
+      |
+      v
+Identify Needed Reference Codes
+      |
+      v
+Expand Specific Sections (Read tool)
+      |
+      v
+Execute Task with Loaded Context
+      |
+      v
+(Optional) Update Indexes if Files Changed
+```
+
+---
+
+## Summary
+
+| Step | Action |
+|------|--------|
+| 1 | Load `_index.mdc` for relevant folder |
+| 2 | Identify reference codes needed for task |
+| 3 | Use Read tool with specific line ranges |
+| 4 | Use content for current task |
+| 5 | Update index if source files change |

package/skills/plan-flow/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: plan-flow
+description: Structured AI-assisted development workflows - discovery, planning, execution, code reviews, and testing
+metadata: {"openclaw":{"requires":{"bins":["git","gh"]}}}
+homepage: https://github.com/brunoscardoso/plan-flow
+user-invocable: true
+---
+
+# Plan-Flow: Structured AI-Assisted Development
+
+A comprehensive skill set for AI-assisted software development with structured workflows.
+
+## 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 |
+
+## 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
+```
+
+## Critical Rules
+
+1. **Automated Workflow**: Run discovery → plan → execute automatically. Only stop to ask when you need information from the user.
+2. **Discovery First**: Always run `/discovery` before `/create-plan` for new features or bugs.
+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:
+
+```yaml
+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
+
+```bash
+clawhub install plan-flow
+```
+
+Or add to your workspace skills folder:
+
+```bash
+git clone https://github.com/brunoscardoso/plan-flow.git ~/.openclaw/skills/plan-flow
+```

package/skills/plan-flow/create-contract/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: create-contract
+description: Create an integration contract from API documentation
+metadata: {"openclaw":{"requires":{"bins":["git"]}}}
+user-invocable: true
+---
+
+# Create Contract
+
+Create an integration contract document from API documentation.
+
+## What It Does
+
+1. Fetches or reads API documentation
+2. Extracts endpoints, schemas, and authentication details
+3. Creates TypeScript interfaces for all data types
+4. Documents error handling and rate limits
+5. Provides usage examples
+
+## Usage
+
+```
+/create-contract <url>
+```
+
+**Arguments:**
+- `url` (required): URL to the API documentation
+
+## Output
+
+Creates: `flow/contracts/<service>_contract.md`
+
+## Contract Structure
+
+```markdown
+# Contract: [Service Name]
+
+Source: [URL]
+
+## Overview
+Brief description of the API
+
+## Authentication
+```typescript
+// Authentication example
+const headers = {
+  'Authorization': `Bearer ${token}`,
+};
+```
+
+## Base Configuration
+| Setting | Value |
+|---------|-------|
+| Base URL | https://api.example.com |
+| Rate Limit | 100 req/min |
+| Timeout | 30s |
+
+## Endpoints
+
+### GET /users
+Get list of users
+
+**Request:**
+```typescript
+interface GetUsersRequest {
+  page?: number;
+  limit?: number;
+}
+```
+
+**Response:**
+```typescript
+interface GetUsersResponse {
+  data: User[];
+  meta: { total: number };
+}
+```
+
+## TypeScript Interfaces
+```typescript
+interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+```
+
+## Error Handling
+| Code | Meaning | Action |
+|------|---------|--------|
+| 401 | Unauthorized | Refresh token |
+| 429 | Rate Limited | Retry with backoff |
+
+## Usage Examples
+```typescript
+// Fetch users
+const users = await api.getUsers({ page: 1 });
+```
+```
+
+## Example
+
+```
+/create-contract https://api.stripe.com/docs
+```
+
+**Output:**
+```
+Creating contract for: https://api.stripe.com/docs
+
+Fetching documentation...
+Extracting endpoints...
+Generating TypeScript interfaces...
+
+Contract created: flow/contracts/stripe_contract.md
+
+Summary:
+- 45 endpoints documented
+- 28 TypeScript interfaces
+- Authentication: Bearer token
+- Rate limit: 100 req/sec
+```
+
+## What's Included
+
+- **Overview**: Service description and version
+- **Authentication**: How to authenticate requests
+- **Endpoints**: All available endpoints with schemas
+- **TypeScript Interfaces**: Types for all request/response data
+- **Error Handling**: Error codes and recommended actions
+- **Rate Limits**: Throttling information
+- **Usage Examples**: Code snippets for common operations
+
+## Use Cases
+
+- Integrating with third-party APIs
+- Documenting internal APIs
+- Creating type-safe API clients
+- Onboarding new developers

package/skills/plan-flow/create-plan/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: create-plan
+description: Create a structured implementation plan with phases and complexity scores
+metadata: {"openclaw":{"requires":{"bins":["git"]}}}
+user-invocable: true
+---
+
+# Create Plan
+
+Create a structured implementation plan based on a discovery document or user input.
+
+## What It Does
+
+1. Extracts requirements from discovery document (or user input)
+2. Analyzes scope and complexity
+3. Structures phases with complexity scores (0-10)
+4. Assigns tasks to each phase
+5. Ensures tests are always the last phase
+
+## Usage
+
+```
+/create-plan <discovery_document>
+/create-plan "<feature_description>"
+```
+
+**Arguments:**
+- `discovery_document`: Path to discovery document (recommended)
+- `feature_description`: Direct description of feature (if no discovery)
+
+## Output
+
+Creates: `flow/plans/plan_<feature>_v<version>.md`
+
+## Complexity Scoring
+
+| 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 |
+
+## Plan Structure
+
+```markdown
+# Plan: [Feature Name]
+
+## Overview
+Brief description
+
+## Goals
+- Goal 1
+- Goal 2
+
+## Phases
+
+### Phase 1: [Name]
+**Scope**: What this phase covers
+**Complexity**: X/10
+
+- [ ] Task 1
+- [ ] Task 2
+
+**Build Verification**: Run `npm run build`
+
+### Phase N: Tests (Final)
+**Scope**: Write comprehensive tests
+**Complexity**: X/10
+
+- [ ] Unit tests
+- [ ] Integration tests
+
+## Key Changes
+1. **Category**: Description
+```
+
+## Example
+
+```
+/create-plan @flow/discovery/discovery_user_auth_v1.md
+```
+
+## Critical Rules
+
+- **No Code**: Plans describe what to implement, not how to code it.
+- **Tests Last**: Tests are always the final phase.
+- **No Auto-Chaining**: Do NOT auto-invoke `/execute-plan`.
+
+## Next Command
+
+After creating a plan, review it and then run `/execute-plan @flow/plans/plan_<feature>_v1.md`.