Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "propulsion",
"version": "1.1.0",
"version": "1.1.1",
"description": "Opinionated agentic coding workflow that guides software work from exploration and planning through execution and review.",
"author": {
"name": "Moon Pixels"
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "propulsion",
"version": "1.1.0",
"version": "1.1.1",
"main": "./index.mjs",
"exports": "./index.mjs",
"scripts": {
Expand Down
8 changes: 4 additions & 4 deletions skills/brainstorm/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Create an approved PRD through repo inspection and interrogation. U

# Brainstorm

Turn vague feature, UX, API, product-scope, or requirements work into an approved PRD.
Turn feature, UX, API, product-scope, or requirements work into an approved PRD.

## Prerequisites

Expand All @@ -18,7 +18,7 @@ ALL prerequisites MUST be satisfied BEFORE following this skill.
Follow these steps IN ORDER. Do NOT skip steps.

1. Load `interrogate` skill and interview the user about their request.
2. Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` using the template in [references/prd-template.md](references/prd-template.md).
2. Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` from [references/prd-template.md](references/prd-template.md).
3. Maliciously sanity-check `prd.md` against the conversation and add any missing decisions, facts, constraints, behaviours, or success criteria.
4. Ask the user to review and approve `prd.md`.
5. After explicit approval, enter the `plan` skill.
Expand All @@ -27,9 +27,9 @@ Follow these steps IN ORDER. Do NOT skip steps.

These rules are MANDATORY.

- ALWAYS use `interrogate` skill to reach a shared understanding BEFORE writing the PRD.
- ALWAYS use `interrogate` skill to reach shared understanding BEFORE writing the PRD.
- ALWAYS use the PRD template for structure and section order.
- MUST keep the PRD product-facing while recording durable implementation and testing decisions.
- MUST keep the PRD product-facing and record durable implementation and testing decisions.
- ENSURE the PRD includes ALL relevant decisions, even if they seem obvious or minor.
- USE supporting documents such as `docs/propulsion/.../diagrams.md` if needed.
- If you cannot write files, STOP, ask the user to enable write mode before continuing the PRD.
Expand Down
36 changes: 15 additions & 21 deletions skills/brainstorm/references/prd-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,34 +15,29 @@ Describe the proposed behaviour end-to-end from the user's perspective.

## Goals

- Goal 1
- Goal 2
- Goal

## Non-Goals

- Explicit non-goal 1
- Explicit non-goal 2
- Explicit non-goal

## User Stories

| ID | User Story |
| ------ | ---------------------------------------------------- |
| US-001 | As a <actor>, I want <behaviour>, so that <benefit>. |
| US-002 | As a <actor>, I want <behaviour>, so that <benefit>. |

## Functional Requirements

| ID | Requirement |
| ------ | -------------------------------------------- |
| FR-001 | When <context>, the system must <behaviour>. |
| FR-002 | The system must <behaviour> when <context>. |

## Non-Functional Requirements

| ID | Category | Requirement |
| ------- | ----------- | --------------------------------------------- |
| NFR-001 | Performance | <operation> must complete within <threshold>. |
| NFR-002 | Security | The system must <security requirement>. |

## Implementation Decisions

Expand All @@ -52,9 +47,8 @@ Describe the proposed behaviour end-to-end from the user's perspective.

## Implementation Inputs

- External links or references to check out
- Business rules or constraints that must be respected
- References to tickets, docs, or other internal resources that are relevant to implementation
- External links, tickets, docs, or references
- Business rules or constraints

## Testing Decisions

Expand All @@ -78,15 +72,15 @@ These rules are MANDATORY.

- ALWAYS follow the template structure and section order exactly as specified.
- MUST use the following non-functional requirement categories:
- Performance: Response times, throughput, and resource utilisation under normal and peak loads.
- Reliability: System availability, fault tolerance, and error recovery capabilities.
- Security: Data protection, authentication, authorisation, and compliance with relevant standards.
- Usability: User experience, accessibility, and ease of use across different user groups.
- Scalability: Ability to handle increased load and growth in users or data volume.
- Maintainability: Code quality, documentation, and ease of future modifications.
- Compatibility: Cross-platform support, browser compatibility, and integration capabilities.
- Portability: Ability to deploy across different environments and infrastructure.
- Compliance: Adherence to industry standards, regulations, and organisational policies.
- Monitoring: Observability, logging, and alerting capabilities for operational support.
- MUST ensure there's a LONG and EXTENSIVE list of user stories, functional requirements, and non-functional requirements to cover all aspects of the feature.
- Performance: response times, throughput, resource use.
- Reliability: availability, fault tolerance, recovery.
- Security: data protection, authn/authz, compliance.
- Usability: UX, accessibility, ease of use.
- Scalability: growth in load, users, or data.
- Maintainability: code quality, docs, future changes.
- Compatibility: platform, browser, integration support.
- Portability: deployment across environments.
- Compliance: standards, regulations, policies.
- Monitoring: observability, logging, alerting.
- MUST ensure user stories, functional requirements, and non-functional requirements cover all feature aspects.
- DO create supporting documents with mermaid diagrams, data models, or other relevant artefacts if they help clarify the feature or implementation.
6 changes: 3 additions & 3 deletions skills/commit/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Create one safe local git commit from current changes. Use when ask

# Commit

Create exactly one local git commit from safe current changes and report the result.
Create one safe local git commit and report the result.

## Prerequisites

Expand All @@ -17,10 +17,10 @@ ALL prerequisites MUST be satisfied BEFORE following this skill.

Follow these steps IN ORDER. Do NOT skip steps.

1. Inspect current state with `git status --short`, `git diff HEAD`, and `git branch --show-current`.
1. Inspect state with `git status --short`, `git diff HEAD`, and `git branch --show-current`.
2. Stage all local changes with `git add -A`, including untracked files.
3. Unstage every staged secret-like file matching [references/workflow.md](references/workflow.md).
4. Check staged changes after exclusions. If none remain, stop and output exactly `No changes to commit.`
4. Check staged changes after exclusions; if none remain, stop and output exactly `No changes to commit.`
5. Generate a one-line imperative commit subject from the staged diff.
6. Create exactly one local commit with that subject.
7. Run `git status --short` before the final response.
Expand Down
9 changes: 3 additions & 6 deletions skills/commit/references/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,9 @@

## Secret-Like Exclusions

Never commit likely secret files. Always unstage staged files matching these patterns before committing:
Never commit likely secret files. Always unstage these patterns before committing:

- `.env`
- `.env.*`
- `*.pem`
Comment thread
adamwhp marked this conversation as resolved.
Resolved
- `*.key`
- `*.p12`
Expand All @@ -24,12 +23,10 @@ Never commit likely secret files. Always unstage staged files matching these pat

## Commit Message

Use a normal imperative commit subject with this format:
Use a normal imperative commit subject:

- one line only
- short descriptive subject line
- imperative mood
- normal natural wording
- short, descriptive, imperative, natural wording
- no trailing punctuation

## No Committable Changes Output
Expand Down
12 changes: 6 additions & 6 deletions skills/debug/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Handle concrete failures through intake, diagnosis, one-hypothesis

# Debug

Diagnose concrete failures before dispatching one evidence-backed fix loop.
Diagnose concrete failures before one evidence-backed fix loop.

## Prerequisites

Expand All @@ -19,15 +19,15 @@ ALL prerequisites MUST be satisfied BEFORE following this skill.
Follow these steps IN ORDER. Do NOT skip steps.

1. Create or resume `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` from [references/debug-template.md](references/debug-template.md) before diagnosis work.
2. Record report provenance, expected behaviour, actual behaviour, impact, environment, reproduction, prior attempts, and open blockers in `debug.md`.
2. Record provenance, expected and actual behaviour, impact, environment, reproduction, prior attempts, and blockers in `debug.md`.
3. Load `interrogate` ONLY when missing user-answerable intake blocks expected behaviour, reproduction, impact, or environment; record answers and resolved decisions in `debug.md`.
4. Explore only the relevant code, tests, logs, recent changes, ownership, and likely boundaries; record facts and intentional limits in `debug.md`.
4. Explore only relevant code, tests, logs, recent changes, ownership, and likely boundaries; record facts and limits in `debug.md`.
5. Use [references/investigation-loop.md](references/investigation-loop.md) to reproduce, read the full error, reduce, compare working examples, isolate the first bad boundary, and test one diagnosis hypothesis at a time.
6. Gate fix dispatch until `debug.md` has grounded diagnosis evidence, the first bad state or divergence, fix constraints, a falsifier, and one chosen fix hypothesis.
7. Dispatch one fresh bug-worker with [references/bug-worker-prompt.md](references/bug-worker-prompt.md), then dispatch one fresh reviewer with [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md).
8. If review rejects the fix, return findings to the active worker with [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md) while the diagnosis still holds.
8. If review rejects the fix and diagnosis still holds, return findings to the active worker with [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md).
9. If verification, review, or new evidence contradicts the diagnosis, reset to investigation and record the contradicted evidence before any new fix attempt.
10. After 3 failed fix loops, reassess architecture and patterns, record the reassessment, then escalate to the user with evidence and next options.
10. After 3 failed fix loops, reassess architecture and patterns, record it, then escalate with evidence and next options.
11. Close only when fixed and verified, blocked by missing intake, no-repro after documented attempts, or escalated after the 3-loop reassessment path.

## Rules
Expand All @@ -37,7 +37,7 @@ These rules are MANDATORY.
- MUST keep `debug.md` current from entry through closure.
- MUST diagnose before fixing; NEVER make permanent production-code edits in the controller stage.
- MUST use `interrogate` only for missing user-answerable intake, not repo facts the agent can inspect.
- MUST reset instead of pushing through when evidence contradicts the diagnosis or chosen fix hypothesis.
- MUST reset when evidence contradicts the diagnosis or chosen fix hypothesis.
- EVERY fix loop MUST target one chosen fix hypothesis and start with a failing regression test unless `tdd` declares no valuable test.
- MUST record failed hypotheses, blocked/no-repro status, rejected reviews, resets, failed loops, verification, escalation, and closure.

Expand Down
18 changes: 9 additions & 9 deletions skills/debug/references/bug-feedback-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Use this template when returning reviewer findings to the active bug-worker duri
````markdown
**You are a subagent completing work in the Propulsion workflow.**

Your bug-fix attempt was reviewed independently under the `debug` skill. Treat the review as technical claims to verify, not instructions to obey blindly.
Your bug-fix attempt was independently reviewed. Treat review items as technical claims to verify.

## Review Report

Expand All @@ -15,14 +15,14 @@ Your bug-fix attempt was reviewed independently under the `debug` skill. Treat t

Follow these steps IN ORDER. Do NOT skip steps.

1. Read the full review report, current `debug.md`, and active diff.
1. Read the review report, current `debug.md`, and active diff.
2. Triage every reviewer finding as `valid`, `invalid`, or `unclear` before changing code.
3. If any finding is `unclear`, STOP and report `Status: unclear` with the missing evidence; do not change code.
4. Confirm every `valid` finding fits the active chosen fix hypothesis and does not require a new hypothesis.
5. If any valid finding or new evidence contradicts the diagnosis, chosen hypothesis, or fix constraints, STOP, update `debug.md`, and reset back to diagnosis.
6. For each valid in-scope finding, make the minimal correction within the active fix hypothesis only.
7. Keep the regression-test-first requirement intact for any additional code change; if no new test is valuable, record the `tdd` rationale and fallback proof.
8. Re-run the relevant checks and update `debug.md` with finding triage, code changes, verification outcome, and diagnosis status.
4. Confirm each `valid` finding fits the active hypothesis and does not require a new one.
5. If a valid finding or new evidence contradicts diagnosis, hypothesis, or constraints, STOP, update `debug.md`, and reset to diagnosis.
6. For each valid in-scope finding, make the minimal correction within the active hypothesis only.
7. Preserve regression-test-first for any code change; if no new test is valuable, record the `tdd` rationale and fallback proof.
8. Re-run relevant checks and update `debug.md` with triage, code changes, verification, and diagnosis status.
9. Return an implementation report in the exact format defined below.

## Output
Expand Down Expand Up @@ -67,8 +67,8 @@ These rules are MANDATORY.
- Preserve the diagnosis reset and one-hypothesis discipline.
- Triage every finding before changing code.
- Do not continue coding once the diagnosis is contradicted.
- Preserve the one-hypothesis, one-fix-loop discipline.
- Do not start a second fix hypothesis inside feedback handling; if a finding requires one, update `debug.md` and reset back to diagnosis.
- Preserve one-hypothesis, one-fix-loop discipline.
- Do not start a second fix hypothesis inside feedback handling; if one is required, update `debug.md` and reset to diagnosis.
- Do not broaden the active fix beyond reviewer findings that fit the chosen fix hypothesis.
- Update `debug.md` before handing control back to `debug`.
- MUST return exactly one `Status:` field with `done`, `blocked`, or `unclear`.
Expand Down
Loading