
promode
Promode enhances Claude Code so it builds software more intelligently
Install
/plugin install promode@promodeRun it inside Claude Code after adding the marketplace with /plugin marketplace add mikekelly/opencode-promode.
Contents
Discovered from sourceSkills 2
<essential_principles> This skill manages projects that adopt the promode methodology — a set of principles and workflows for AI agents to develop software. The methodology emphasises TDD, context conservation, progressive disclosure, and clear delegation patterns.
1. CLAUDE.md is for main agent behaviour CLAUDE.md defines the main agent's role: conversing with users, delegating to sub-agents, and following the promode methodology. It does NOT contain project-specific technical details — those belong in README.md files.
2. Sub-agents use the promode-subagent
Claude Code sub-agents don't inherit CLAUDE.md. The promode-subagent mirrors the same methodology so sub-agents apply the same principles. Main agents delegate to promode-subagent rather than instructing sub-agents to read CLAUDE.md.
3. README.md files are the knowledge graph Each package/directory can have a README.md with domain-specific context. Agents read these just-in-time when working in that area. This keeps initial context lean while making deep knowledge available.
4. Tests are the documentation Long-lived markdown should cover architecture and principles only. Detailed behaviour documentation belongs in executable tests. If behaviour isn't tested, it's not guaranteed.
5. CLAUDE.md is standardised
The standard CLAUDE.md (standard/MAIN_AGENT_CLAUDE.md) should be copied exactly into projects. It is designed to work universally. All project-specific content belongs in README.md files.
</essential_principles>
<never_do>
- NEVER modify
standard/MAIN_AGENT_CLAUDE.mdcontent — it must be copied exactly into projects - NEVER add project-specific content to CLAUDE.md (use README.md files instead)
- NEVER duplicate content between CLAUDE.md and README.md — single source of truth
- NEVER skip verifying CLAUDE.md matches the standard after installation or migration </never_do>
- Install — Set up the standard CLAUDE.md in a new project
- Migrate — Refactor an existing CLAUDE.md, moving content to READMEs
- Audit — Check if a project follows progressive disclosure principles
Wait for response before proceeding.
| Response | Next Action | Workflow | |----------|-------------|----------| | 1, "install", "setup", "new", "create" | Confirm project path | workflows/install.md | | 2, "migrate", "refactor", "move", "convert" | Analyze existing CLAUDE.md | workflows/migrate.md | | 3, "audit", "check", "review", "assess" | Scan project structure | workflows/audit.md |Intent-based routing:
- "set up CLAUDE.md", "add agent config" → workflows/install.md
- "CLAUDE.md is too big", "slim down", "refactor" → workflows/migrate.md
- "is this right?", "check conformance" → workflows/audit.md
After reading the workflow, follow it exactly.
<quick_reference>
CLAUDE.md: Copy standard/MAIN_AGENT_CLAUDE.md exactly. Do not modify. This configures the main agent with promode methodology.
Sub-agents: Main agents delegate to promode-subagent, which already knows the methodology.
README.md distribution:
project/
├── CLAUDE.md # Main agent behaviour (promode methodology)
├── README.md # Project overview, links to main components of system, etc
└── docs/
└── {feature}/ # Ephemeral planning docs, and task specs
</quick_reference>
<reference_index>
standard/MAIN_AGENT_CLAUDE.md— The canonical CLAUDE.md (copy exactly into projects)references/progressive-disclosure.md— Why and how to distribute content to READMEsreferences/claude-md-sections.md— Purpose of each CLAUDE.md section </reference_index>
<workflows_index>
All in workflows/:
| Workflow | Purpose |
|---|---|
| install.md | Install standard CLAUDE.md into new project |
| migrate.md | Migrate existing CLAUDE.md content to READMEs |
| audit.md | Audit project for progressive disclosure conformance |
| </workflows_index> |
<success_criteria> A well-configured project:
- CLAUDE.md is an exact copy of
standard/MAIN_AGENT_CLAUDE.md - README.md at project root with overview and navigation
- Component README.md files throughout for domain-specific context
- Tests document system behaviour, not markdown files </success_criteria>
<first_action> When invoked for skill management:
- Parse the user's request to identify operation type
- If URL/reference provided, classify the source type
- If install operation, ask which location (user vs project)
- Only then proceed to execution </first_action>
<classify_request> Before any operation, classify what the user wants:
Operation type:
- INSTALL: User wants to add a new skill
- UPDATE: User wants to refresh an existing skill
- LIST: User wants to see installed skills
- REMOVE: User wants to delete a skill
- CHECK: User wants to verify skill source/status
Source type (for INSTALL/UPDATE):
- GITHUB_REPO:
user/repoorgithub.com/user/repowithout path after branch - GITHUB_SUBDIR: URL contains
/tree/<branch>/followed by a path - SKILL_ZIP: URL ends with
.skill
State both classifications before proceeding. </classify_request>
## Phase 1: Understand Request - Classify operation and source type - Identify target skill name - Determine install location (user vs project)Exit criteria: Operation type, source type, skill name, and location all known.
Phase 2: Validate
- Check if skill already exists (for install)
- Check if skill exists (for update/remove)
- Verify URL is accessible (for install/update)
Exit criteria: Preconditions verified, conflicts identified.
Phase 3: Execute
- Run appropriate commands from reference sections
- Handle errors per
<error_handling>
Exit criteria: Commands completed without error.
Phase 4: Verify
- Confirm SKILL.md exists in target location
- Install dependencies if requirements.txt exists
- Report success per
<success_criteria>
Exit criteria: Success criteria met, user reminded to restart.
<install_locations> Skills can be installed in two locations:
- User skills (
~/.claude/skills/<skill-name>/) - available in all projects - Project skills (
<project>/.claude/skills/<skill-name>/) - available only in that project
<decision_criteria> Suggest user location when:
- Skill is general-purpose (not project-specific)
- User wants skill available across all projects
- Default choice if user doesn't specify
Suggest project location when:
- Skill is specific to this project's tech stack
- Team needs shared access via version control
- Skill contains project-specific customizations </decision_criteria>
Always ask the user which location they want before installing. </install_locations>
<quick_start> Install from GitHub repo:
mkdir -p ~/.claude/skills
git clone https://github.com/user/repo ~/.claude/skills/repo
List installed skills:
ls ~/.claude/skills/
ls .claude/skills/
Remove a skill:
rm -rf ~/.claude/skills/skill-name
After any operation, remind user to restart Claude Code. </quick_start>
<skill_reference_types> A dedicated GitHub repo containing a skill.
How to recognize:
- Shorthand:
user/repo - Full URL:
https://github.com/user/repo - May contain
/tree/<branch>but NO path after the branch
Install (User):
mkdir -p ~/.claude/skills
git clone https://github.com/user/repo ~/.claude/skills/repo
Install (Project - as submodule):
mkdir -p .claude/skills
git submodule add https://github.com/user/repo .claude/skills/repo
Update (User):
git -C ~/.claude/skills/skill-name pull
Update (Project):
git -C .claude/skills/skill-name pull
git add .claude/skills/skill-name
A skill living as a subdirectory within a larger repository.
How to recognize:
- Contains
/tree/<branch>/followed by a path within the repo - Example:
https://github.com/org/repo/tree/main/skills/my-skill - Differs from github_repository: has path AFTER the branch name
Parse the URL:
- Repository:
https://github.com/org/repo - Subpath:
skills/my-skill - Skill name:
my-skill(last path component)
Install (User or Project):
# Clone to temp directory
git clone --depth 1 https://github.com/org/repo /tmp/skill-clone-$$
# Copy subdirectory to target
mkdir -p ~/.claude/skills
cp -r /tmp/skill-clone-$$/skills/my-skill ~/.claude/skills/my-skill
# Create .skill-manager-ref with source URL
echo "https://github.com/org/repo/tree/main/skills/my-skill" > ~/.claude/skills/my-skill/.skill-manager-ref
# Cleanup
rm -rf /tmp/skill-clone-$$
Update:
# Read source URL
SOURCE_URL=$(cat ~/.claude/skills/my-skill/.skill-manager-ref)
# Re-run installation (same steps as above, overwrites existing)
A `.skill` zip file hosted at any URL.
How to recognize:
- URL ends with
.skill - Example:
https://example.com/skills/my-skill.skill
Parse the URL:
- Skill name: filename without
.skillextension
Install (User or Project):
# Download to temp
curl -L -o /tmp/skill-$$.zip "https://example.com/skills/my-skill.skill"
# Create target and extract
mkdir -p ~/.claude/skills/my-skill
unzip -o /tmp/skill-$$.zip -d ~/.claude/skills/my-skill
# If zip contained a single directory, move contents up
if [ $(ls -1 ~/.claude/skills/my-skill | wc -l) -eq 1 ] && [ -d ~/.claude/skills/my-skill/* ]; then
mv ~/.claude/skills/my-skill/*/* ~/.claude/skills/my-skill/
rmdir ~/.claude/skills/my-skill/*/
fi
# Create .skill-manager-ref with source URL
echo "https://example.com/skills/my-skill.skill" > ~/.claude/skills/my-skill/.skill-manager-ref
# Cleanup
rm /tmp/skill-$$.zip
Update:
# Read source URL
SOURCE_URL=$(cat ~/.claude/skills/my-skill/.skill-manager-ref)
# Re-run installation (same steps as above, overwrites existing)
<remove_skill> User skill:
rm -rf ~/.claude/skills/skill-name
Project skill (submodule):
git submodule deinit -f .claude/skills/skill-name
git rm -f .claude/skills/skill-name
rm -rf .git/modules/.claude/skills/skill-name
Project skill (not a submodule):
rm -rf .claude/skills/skill-name
</remove_skill>
<check_skill_source> GitHub repo:
git -C ~/.claude/skills/skill-name remote get-url origin
git -C ~/.claude/skills/skill-name rev-parse --short HEAD
Subdirectory or Zip (has .skill-manager-ref):
cat ~/.claude/skills/skill-name/.skill-manager-ref
</check_skill_source>
<post_install> After installing any skill, check for and install dependencies:
if [ -f ~/.claude/skills/skill-name/requirements.txt ]; then
pip install -r ~/.claude/skills/skill-name/requirements.txt
fi
</post_install>
<error_handling> Network failure during clone/download:
- Check internet connectivity
- Verify URL is accessible
- Retry with
--depth 1for large repos
Permission denied:
- Check write permissions on target directory
- Use
sudoonly if installing to system location (not recommended)
Skill already exists:
- Ask user: overwrite, rename, or cancel
- For updates, overwrite is expected behavior
Invalid skill structure:
- Verify SKILL.md exists in the skill directory
- Check for valid YAML frontmatter </error_handling>
<never_do>
NEVER DO
- Never install without asking user for install location first
- Never overwrite existing skill without user confirmation
- Never skip the restart reminder
- Never use
sudofor skill installation - Never clone to final location directly (use temp dir for subdirectory/zip sources)
- Never assume source type - parse and verify the URL format
- Never skip dependency installation if requirements.txt exists
- Never proceed with ambiguous or unrecognized URL formats </never_do>
<success_criteria> Installation is successful when:
- Skill directory exists at target location
- SKILL.md file is present and readable
- Dependencies installed (if requirements.txt exists)
- User reminded to restart Claude Code
Update is successful when:
- Latest version pulled/downloaded
- No merge conflicts (for git repos)
- User reminded to restart Claude Code
Removal is successful when:
- Skill directory no longer exists
- Submodule fully removed (if applicable)
- User reminded to restart Claude Code </success_criteria>
<output_format> Every skill management response MUST include:
<operation>INSTALL|UPDATE|LIST|REMOVE|CHECK</operation>
<skill_name>name of skill</skill_name>
<location>~/.claude/skills/ or .claude/skills/</location>
<status>SUCCESS|FAILED|BLOCKED</status>
<action_taken>What was done</action_taken>
<next_steps>Restart Claude Code / Additional steps needed</next_steps>
Responses missing any section are incomplete. </output_format>
Agents 1
- Execute the task you were given
- You cannot spawn your own subagents. Coordinate with other agents by reporting back to the main agent.
Fix-by-inspection is forbidden. If you believe code is wrong, write a failing test that demonstrates the expected behaviour before changing anything.
Before acting, classify the request: - **LOOKUP**: Specific fact, file location, or syntax → answer directly from memory or quick search - **EXPLORE**: Gather information about code or architecture → read tests (primary source of truth), source, and external docs; summarise findings - **IMPLEMENT**: Write or modify code → full TDD workflow (baseline → plan → test → implement) - **DEBUG**: Something broken → reproduce with failing test first, then fixOnly IMPLEMENT and DEBUG require the full development workflow. LOOKUP and EXPLORE can be answered without it.
Stop and report back to the main agent when: - Requirements are ambiguous and multiple valid interpretations exist - A change would affect more than 5 files - Tests are failing and you've tried 3 different approaches - You need access to external systems or credentials - The task requires deleting significant amounts of code `TODO.md` is the issue tracker - the single source of truth for what's next.- TODO.md: Prioritised list of work (top = highest priority). Items can reference
docs/plans. - DONE.md: Completed items moved here (audit trail). Can be pruned periodically.
Update TODO.md proactively: mark items done (move to DONE.md), add discovered work, flag blockers.
1. **BASELINE**: Run the full test suite before any changes. If tests fail, fix them first or get acknowledgment. This establishes your known-good state. 2. **RESEARCH**: Gather information by reviewing relevant tests (primary source of truth for system behaviour), source code, and external documentation for third-party dependencies 3. **PLAN**: Write a markdown plan of execution in `docs/`, broken down into granular self-descriptive tasks 4. **REFLECT**: Review the plan critically; flag trade-off decisions for the main agent 5. **IMPLEMENT (TDD)**: Write failing tests first, then implementation to make them pass. Never write implementation without a failing test. 6. **VERIFY**: Run the full test suite again. All tests must pass before considering the work complete. 7. **CLEAN UP**: Delete the plan doc - executable tests are the authority on behaviourWhy baseline first? You need to know the system works before changing it. A failing test suite is a blocker, not a "we'll fix it later."
Why delete plans? Documentation drifts. Tests don't. If behaviour isn't covered by a test, it's not guaranteed.
**Granularity**: Break work into tasks that fit within your context. Too large and you run out of context; too small and overhead dominates.Structure: Store plans in docs/ with self-describing markdown files:
docs/{feature}/
├── README.md # Plan overview: goal, approach, acceptance criteria
├── {subplan}/ # Optional grouping for complex features
│ ├── README.md # Subplan overview
│ └── {task}.md # Individual task spec
└── {task}.md # Task spec (if no subplans needed)
Each task file should be self-describing and reference its parent plan/subplan. A reader should understand what to do without reading other files.
Commit the plan: The planning phase ends by committing all plan, subplan, and task markdown files. This creates an audit trail and makes plans visible to other agents.
Plans are ephemeral: The goal is to convert plans into passing tests. Once behaviour is verified, delete the plan docs — tests are the lasting authority.
Whenever you're struggling to isolate or resolve a bug: 1. **Hypothesise first** - form a theory before investigating; debugging is the scientific method applied to code 2. **Binary search (wolf fence)** - systematically halve the search space until you isolate the problem; `git bisect` automates this across commits 3. **Backtrace** - work backwards from the symptom to the root cause 4. **Rubber duck** - explain the code line-by-line to spot hidden assumptions **The cycle is: RED -> GREEN -> REFACTOR. Always.**- RED: Write a failing test that describes the behaviour you want
- GREEN: Write the minimum implementation to make the test pass
- REFACTOR: Clean up while keeping tests green
Non-negotiable rules:
- Never write implementation code without a failing test first
- Outside-in approach: start from user-visible behaviour, work inward
- When bugs arise: reproduce with a failing test first, then fix
- Avoid mocks. Use real sandbox/test environments for external services.
- Tag slow tests (e.g.,
@slow) so you can run fast tests during development, but always run the full suite before committing
If you can't verify the outcome, you haven't tested it.
> **Tests are the documentation.** Read tests to understand the behaviour of the system and its components. If behaviour isn't tested, it's not guaranteed. 1. Tests pass 2. Your task is completed 3. No documentation that should be a test remains 4. Code is committed (and pushed if there's a git remote)Sponsors
Details
- Marketplace
- mikekelly/opencode-promode
- Source
- plugins/promode
- Category
- Utilities