motspilot.sh
The Filing SystemShell utility that manages named tasks, requirements, state, checkpoints, and artifacts. Does not invoke AI directly.
Claude Code
The EngineAI orchestrator that reads work orders and runs each pipeline phase as a Task subagent. Fully automatic by default (AUTO_APPROVE="all"); switch to "none" to approve each phase before it proceeds.
Pipeline at a Glance
Consensus queries 3 AIs (Claude + GPT-4o + Gemini) before pipeline starts — optional human approval gates between phases (AUTO_APPROVE="none")
Install as a Claude Code Plugin (recommended)
From any Claude Code session:
/plugin install mots
Then in your target project:
/mots:pilot add login throttling # Run the pipeline
/mots:status # Check progress
/mots:view verify # Read verification report
/mots:archive --task=add-login-throttling # Archive when done
Quick Start (shell / clone)
# Edit .motspilot/config with your language, framework, and test command
Task Lifecycle
Edit tasks/<name>/01_requirements.md — describe what you want built, acceptance criteria, constraints.
AUTO_APPROVE="none")
Review summary after each phase → [A]pprove, [R]eject with feedback, or [V]iew full artifact. Skipped entirely under the default AUTO_APPROVE="all".
When delivery is approved, task moves to archive/ automatically. Status: completed
$ ./motspilot.sh go --task=my-feature --from=development
Multi-Task Scenarios
New Feature
# Previous task paused automatically
Resume Paused Task
Bug Fix on Archived Task
$ ./motspilot.sh go --task=task-name --from=development
See All Tasks
$ ./motspilot.sh tasks --all # + archived
Checkpointing & Resumption
After each approved phase, a checkpoint is saved to tasks/<name>/checkpoint.
- Format:
<phase>|approved(e.g.,development|approved) - Resume from any phase:
./motspilot.sh go --task=name --from=testing - State persists on disk — works across sessions
- Artifacts serve as the persistent context bridge between sessions
Before the phases begin, a multi-model consensus step queries 3 AIs in parallel and synthesizes a unified starting context (9-section structured format with Agreed/Split/Risks/Scope sections). Each phase prompt includes YAML frontmatter (parsed by yq), a <hard_constraints> block of non-negotiable rules as the first content the AI reads, and a thinking framework (not a checklist). Every phase produces an <analysis>/<summary> output split — scratch work stays on disk, only clean summaries flow downstream. Further techniques: XML-tagged prompt assembly, investigate-before-acting guards, anti-overengineering clauses, structured 12-item <completion_checklist> blocks, <tool_affinity> rules, few-shot examples, quote-grounded findings with mandatory file:line evidence, confidence scoring (1–10), adversarial anti-patterns, and constants discipline. Verification adds the MUST FIX (untested seam) non-downgradeable severity tier, four mechanical consistency checks, and a terse VERDICT: first line; delivery executes smoke tests with an entry-point + side-effect requirement. Optional parallel 3-lens review fans out Architecture and Verification into 3 specialist subagents for medium/large features. For the full catalogue of patterns, see docs/prompt-engineering.md.
Requirements — Input you write (not an AI phase)
No codeDescribe what you want built: user stories, acceptance criteria, data requirements, UI specs, security constraints, and what's out of scope.
Artifact:01_requirements.md
Multi-Model Consensus — 3 AIs before pipeline starts
AutomaticFans out the task requirements to Claude + GPT-4o + Gemini in parallel, collects all responses, then synthesizes via a 3-pass process (Extract → Reconcile → Synthesize) into a 9-section structured format (Agreed/Split/Risks/Scope sections) with completeness verification. Split decisions auto-resolve by majority when AUTO_APPROVE=all. Fault-tolerant by design: if 1–2 APIs fail, synthesis proceeds with the remaining responses; if all 3 fail, the pipeline continues without consensus and logs the gap.
consensus/01_claude.md — Full Claude responseconsensus/02_gpt4o.md — Full GPT-4o responseconsensus/03_gemini.md — Full Gemini responseconsensus/04_synthesis.md — Judge-merged unified outputconsensus/05_differences.md — Unique contributions per AI (what each brought that others missed)
bin/consensus.php — PHP 8+, no framework dependencies. API keys in .env. Fault-tolerant: works with 1-3 models. Dynamic timeouts scale with prompt length (60–300s).
Architecture — Design only
No codeExplores the codebase, understands existing patterns, traces blast radius, and produces a comprehensive design document. Includes <hard_constraints>, <investigate_before_designing> guard, <anti_overengineering> clause, assumption-gating, YAML frontmatter, <analysis>/<summary> output split, and a 12-item <completion_checklist>. Large features are decomposed into 5–30 discrete implementation units. Optional parallel 3-lens review (integration-fit / blast-radius / testability) for medium/large features.
- Start with the person — Who uses this? What's their goal? What do they see?
- Get a feel for the codebase — Read landmark files. What conventions exist? What would look natural?
- Trace the blast radius — What could break? Map dependencies. Every line is a potential failure.
- Design by asking questions — Data, logic, security, failure. Not by following templates.
- Consider alternatives — Think of 2+ approaches, explain why you chose one.
- User Experience
- Codebase Analysis
- Blast Radius
- Data Design
- Component Design
- Security Design
- Failure Modes
- Alternatives Considered
- File Map (new + modified)
- Rollback Plan
02_architecture.md
Development — Build in tiny loops
Writes codeImplements the feature following the architecture document. Creates and modifies actual files in the codebase. Includes <hard_constraints>, <investigate_before_coding> guard, <anti_overengineering> clause, <tool_affinity> rules (routes AI toward Grep/Edit over Bash equivalents), <one_in_progress> rule (one WIP item at a time), <analysis>/<summary> output split, and a 12-item <completion_checklist>. Each build layer includes a Success signal defining when to advance. BLOCKER markers and smoke tests use dual-form naming (imperative + present-continuous).
Loop 1 — Foundation: Schema/migration → model/entity → relationships → verify
Loop 2 — Logic: Service method → test → green → next method → test → green
Loop 3 — Interface: Controller/handler → template/view → routes → verify in browser
- Read every file you'll modify before changing it
- Surgical additions only — never reformat or restructure
- Match the existing coding style exactly
- One logical action per migration file
- Legacy patterns: work with them, don't refactor
- Record test baseline before any changes
03_development.md
Testing — Security-first
Writes codeWrites comprehensive tests starting with what scares you most, not what's easiest. Includes <hard_constraints>, <investigate_before_testing> guard, <analysis>/<summary> output split, few-shot <example> blocks for test naming, and a 12-item <completion_checklist>. Falls back to manual test checklists when no test framework exists. Integration-vs-unit hard rule: for any runtime path that runs inside framework plumbing (events, middleware, observers, lifecycle hooks, schedulers, queues), at least one test must exercise the real dispatch mechanism — reflection-based unit tests directly invoking handler methods are not sufficient. The testing summary must include a runtime-path classification table (pure-logic / plumbing-dependent / external-I/O) so verification can cross-check coverage.
- Integration safety — existing tests still pass
- Security — auth bypass, CSRF, mass assignment, IDOR, XSS
- Business logic edge cases — service layer decisions
- Happy path — basic "it works" confirmation
- Error paths — validation, duplicates, missing data
04_testing.md
Verification — Skeptical senior reviewer
No codeReads actual code (not reports), traces data flows, checks for security issues, verifies framework API correctness. Includes <hard_constraints>, <investigate_before_judging> guard, <analysis>/<summary> output split, and a 12-item <completion_checklist>. The <summary> starts with a terse VERDICT: READY | READY WITH NOTES | NOT READY line. Every finding requires file:line + code evidence (findings without evidence are invalid) and a confidence score (1–10; below 7 demotes to non-blocking NOTE). Adversarial <before_pass> and <before_fail> checklists guard against verification avoidance. A dated <hard_exclusions> list suppresses known false-positive patterns. Optional parallel 3-lens review (correctness / consistency / regression) for medium/large features.
- Did anything existing break? (full test suite)
- Does the feature meet requirements? (every criterion)
- Is the code secure? (validation, escaping, auth, IDOR, CSRF)
- Is the code clean? (readable, maintainable)
- Correct framework API for the project's version?
- CRITICAL — security or correctness breakage; blocks delivery.
- MUST FIX (untested seam) — non-downgradeable. Any runtime code path that exists in the shipped change but is not exercised by any test (unit, integration, or smoke). Cannot be deferred as a follow-up note.
- SHOULD FIX — quality or maintainability issue that blocks delivery but is not security-critical.
- IMPROVE — nice-to-have. Only IMPROVE-tier issues are allowed under the
READY WITH NOTESverdict.
- Data-value consistency — string constants, enum values, column values, and config keys agree across all task docs and source code.
- Symbol-name consistency — constant, method, class, and file-path names match across docs and code.
- Timezone consistency — for any time-bucketed column, write-side and read-side must agree explicitly on the timezone.
- Event-name consistency — every listener has at least one matching dispatch site in the target codebase, not only in
vendor/. Dangling listeners flag MUST FIX (untested seam).
05_verification.md — READY / READY WITH NOTES (IMPROVE-tier only) / NOT READY
Delivery — Safe and reversible
No codeProduces deployment guide with copy-paste commands, rollback steps, smoke tests, and monitoring instructions. Includes <hard_constraints>, <investigate_before_documenting> guard, <analysis>/<summary> output split, and a 12-item <completion_checklist>. Surfaces unresolved verification issues with [VERIFY] markers.
Before writing a smoke test, the AI must classify each touched surface (GET-safe action / state-changing HTTP / webhook / CLI / cron / queue / event listener) and pick the matching entry-point shape. The curl-GET template only applies to read-only routes.
Smoke tests are not a post-deploy operator checklist. The delivery phase executes every smoke test before marking the task complete. Each smoke test requires both:
- Entry-point check — HTTP status, CLI exit code, queue arrival
- Side-effect check — DB row, mail catcher (Mailpit/MailHog/smtp4dev) message, file written, cache key updated, external API called
Status-code-only tests count as zero tests. Smoke tests that cannot run in the environment are tagged [UNEXECUTABLE] with a one-sentence justification and surfaced for the operator to run post-deploy.
- What changed (human summary)
- Files (new, modified, deleted)
- Deployment steps
- Rollback steps
- Configuration changes
- Git commit message
- What to watch after deploy
- Known limitations / future work
06_delivery.md
Project Configuration
Edit .motspilot/config — this file is sourced by motspilot.sh and read by the orchestrator.
| Key | Description | Example | Default |
|---|---|---|---|
| PROJECT_ROOT | Path to project root (relative to motspilot/ or absolute) | ".." | .. |
| LANGUAGE | Programming language | "php" | "" (empty) |
| LANGUAGE_VERSION | Language version | "8.2" | "" (empty) |
| FRAMEWORK | Framework name — loads matching guide from prompts/frameworks/ |
"cakephp" | "" (empty) |
| AUTO_APPROVE | Skip approval gates between phases. Default "all" runs fully automatic; set "none" to pause for approval after each phase. |
"all", "none", or comma list e.g. "architecture,delivery" | "all" |
| MAX_RETRIES | Retry budget per phase on failure | 2 | 2 |
| TEST_CMD | How to run tests | "pytest" | "" (empty) |
| APP_URL | URL for smoke testing in verification | "http://localhost:3000" | "http://localhost:8080" |
| DEPLOY_CMD | Deployment command | "./deploy.sh" | "echo 'Deploy not configured'" |
Example Configurations
CakePHP Project
LANGUAGE_VERSION="8.2"
FRAMEWORK="cakephp"
TEST_CMD="./vendor/bin/phpunit"
APP_URL="http://localhost:8080"
Django Project
LANGUAGE_VERSION="3.12"
FRAMEWORK="django"
TEST_CMD="python manage.py test"
APP_URL="http://localhost:8000"
Next.js Project
LANGUAGE_VERSION="5.3"
FRAMEWORK="nextjs"
TEST_CMD="npm test"
APP_URL="http://localhost:3000"
Rails Project
LANGUAGE_VERSION="3.3"
FRAMEWORK="rails"
TEST_CMD="bundle exec rspec"
APP_URL="http://localhost:3000"
Command Reference
| Command | Description |
|---|---|
./motspilot.sh init |
First-time setup — creates config and directory structure |
./motspilot.sh go --task=<name> "description" |
Create task + generate work order |
./motspilot.sh go --task=<name> |
Re-prepare existing task (regenerate work order) |
./motspilot.sh go --task=<name> --from=<phase> |
Prepare to re-run from a specific phase |
./motspilot.sh tasks |
List active tasks with phase progress bars |
./motspilot.sh tasks --all |
List active + archived tasks |
./motspilot.sh status [--task=<name>] |
Detailed task status with artifact sizes |
./motspilot.sh archive --task=<name> |
Manually archive a completed task |
./motspilot.sh reactivate <name> |
Restore task from archive for bug fixes |
./motspilot.sh reset --task=<name> |
Delete phase artifacts (keeps requirements) |
./motspilot.sh view <phase> [--task=<name>] |
View a phase artifact in terminal |
./motspilot.sh mem-check |
Check memory index health (line/byte caps, staleness) |
Phase Names & Shortcuts
Full Phase Names
architecture ·
development ·
testing ·
verification ·
delivery
View Shortcuts
req ·
arch ·
dev ·
test ·
verify ·
wo (workorder)
Framework Guides
Framework-specific knowledge lives in prompts/frameworks/<name>.md. When a guide exists for your configured FRAMEWORK, it's automatically included in every subagent prompt alongside the thinking framework.
Available Guides
cakephp.md
CakePHP 4.x — Version reference, naming conventions, migration/entity/table/service/controller/template/route/test patterns, verification checks, deployment commands, and<framework_tool_affinity> rules. Smoke-test templates assert side effects (mail catcher, DB rows, cache keys) and point at prompts/delivery.md section 3.2 for the execution gate.
plain-php.md
Plain PHP (no framework) — structured around two callouts: Shape A (page-file) and Shape B (PDS-skeleton). Includes webserver isolation rules,<framework_tool_affinity> rules, and side-effect-asserting smoke-test templates that point at prompts/delivery.md section 3.2 for the execution gate.
laravel.md
Laravel 11.x+ — Eloquent, Form Requests, Policies, Events/Queues, Pest/PHPUnit, and artisan commands. Includes<framework_tool_affinity> rules and side-effect-asserting smoke-test templates that point at prompts/delivery.md section 3.2 for the execution gate.
Adding a New Framework Guide
motspilot/prompts/frameworks/<framework-name>.mdFRAMEWORK="<framework-name>" in .motspilot/configRecommended Sections for a Framework Guide
| Section | Purpose | Used by Phase |
|---|---|---|
| Version Reference | Correct vs incorrect API for the framework version | All phases |
| Naming Conventions | How files, classes, routes are named | Architecture, Development |
| Files to Explore | Key landmark files for codebase understanding | Architecture |
| Migration / Schema Patterns | How to create and rollback schema changes | Development |
| Model / Entity Patterns | Access control, validation, relationships | Development |
| Service / Logic Patterns | Where business logic lives | Development |
| Controller / Handler Patterns | Request handling conventions | Development |
| Template / View Patterns | Output escaping, form helpers, layout | Development, Verification |
| Test Patterns | Test setup, fixtures/factories, security test examples | Testing |
| Verification Checks | Grep patterns to catch common mistakes | Verification |
| Deployment Commands | Deploy, rollback, cache clear commands | Delivery |
| Tool Affinity | <framework_tool_affinity> — routes AI toward correct tools for the framework |
Development |
Core Philosophy
These principles guide every phase of the pipeline. They're not rules to follow — they're a way of thinking.
Start with the person
Think about who uses the feature before touching code. What's their goal? Their emotional state? What do they see when things go wrong?
Explore before building
Read existing code. Understand patterns. Don't assume anything about the codebase structure. Your new code should feel like it was always there.
Trace the blast radius
Before changing anything, ask: "What could this break?" Map every dependency between your feature and existing code.
Build in tiny loops
Write a little → verify it works → write more. Never write 500 lines and hope for the best.
Security mindset
Think like an attacker at every step. Test auth bypass, CSRF, IDOR, mass assignment, and XSS before testing the happy path.
Never greenfield
Always integrating into existing apps. Match existing patterns. Work with legacy code, don't refactor it.
One action per migration
Never combine unrelated changes in a single migration. Each migration should do exactly one thing — easier to debug, rollback, and review.
Human in the loop (optional)
Fully automatic by default (AUTO_APPROVE="all"). Set AUTO_APPROVE="none" to enable approval gates between every phase — review, reject, or approve each one.
Prompt Architecture
Each subagent receives a layered prompt assembled by the orchestrator using XML tags for unambiguous section parsing. Phase prompts include YAML frontmatter (parsed by yq) and emit <analysis> (scratch work, stays on disk) + <summary> (clean deliverable forwarded downstream):
<thinking_framework>
[Full contents of prompts/<phase>.md — YAML frontmatter + prompt body]
Includes <hard_constraints>, <investigate_before_*>, <anti_overengineering>, <tool_affinity>, <completion_checklist> (12 items), <example> blocks
</thinking_framework>
<framework_guide>
[Full contents of prompts/frameworks/<FRAMEWORK>.md]
Framework-specific patterns, API reference, verification checks, <framework_tool_affinity>
</framework_guide>
<project_config>
Language, version, framework, test command, app URL
</project_config>
<requirements>
Full contents of 01_requirements.md
</requirements>
<consensus>
Multi-model synthesis — 9-section structured format (omitted if unavailable)
</consensus>
<previous_phases>
<summary> blocks from completed phases (directive, not narrative)
</previous_phases>
<task>
Phase-specific instructions
</task>
</motspilot_phase>
Phase output: <analysis> (scratch, disk only) + <summary> (forwarded) + <task-notification> (completion signal)
Why XML tags? Claude's prompt engineering best practices recommend XML tags over plain-text markers for unambiguous parsing of multi-section prompts. Each section is clearly delineated, reducing misinterpretation when mixing instructions, context, examples, and variable inputs. The canonical list of all XML tags is in prompts/_xml_tags.md.