SuperDev

Core Rule

Use spec / plan driven development for durable work:

• Maintain root SPEC.md and PLAN.md for repository-wide architecture and execution state.
• Maintain <module>/SPEC.md and <module>/PLAN.md for every long-lived module.
• Require every substantial SPEC.md to include both Current Architecture and Target Architecture Mermaid diagrams.
• Do not begin substantial production implementation until the target Mermaid architecture is clear enough to guide the work.

Small one-off utilities, copy edits, typo fixes, and local experiments do not need new module docs unless they become durable subsystems.

Maintenance and Git publication are separate decisions. Keep SuperDev documents local by default unless the repository deliberately uses them as shared documentation.

Git Publication Policy

Treat SPEC.md and PLAN.md as local Agent working memory by default. SuperDev requires maintaining them; it does not require publishing them.

• Do not stage, commit, or push newly created or untracked SPEC.md or PLAN.md files unless the user explicitly asks to publish them or the repository already treats them as shared architecture documentation.
• In a Git worktree, add the exact untracked paths to .git/info/exclude by default. Prefer this local-only exclusion over changing the repository's shared .gitignore.
• Before any commit or push, inspect git status and keep local SuperDev documents out of the staged set. Do not let broad staging commands decide whether they are published.
• If a SPEC.md or PLAN.md is already tracked, continue maintaining it but do not include its changes in a commit by default and do not silently untrack it. Explain that ignore rules do not affect tracked files; use git rm --cached only when the user explicitly authorizes making the file local-only.
• Explicit user instructions and established repository policy override this default.

Tracking can be appropriate when these files are intentionally part of a team's architecture contract. Volatile execution plans should usually remain local, especially in public repositories.

Main Session Runtime

Use the model and reasoning effort already active in the main Codex session. Never inspect, request, require, verify, or switch the main-session profile, and never block implementation because a particular model or reasoning level cannot be confirmed. SuperDev gates work on architecture clarity, not model identity.

Development Gate

Before substantial code changes:

1. Identify whether the request touches repository-wide behavior, one long-lived module, or multiple modules.
2. Read the root SPEC.md and PLAN.md when they exist.
3. Read each relevant module's SPEC.md and PLAN.md when they exist.
4. Check whether each relevant SPEC.md has:
   • Current Architecture with a Mermaid diagram that matches the current implementation.
   • Target Architecture with a Mermaid diagram that matches the requested direction.
5. If docs are missing, stale, or unclear, update or discuss the docs first.

If Target Architecture is absent, stale, or incomplete, infer and draft the most reasonable target from the request, current code, and existing architecture before asking the user. A missing diagram alone is not a reason to interrupt the user. Pause only when no safe target can be inferred under the rules below.

Target Alignment

Treat target alignment as model-led reasoning, not a mandatory approval ceremony:

1. Infer the intended target from the request, current implementation, and Current Architecture.
2. Draft or update the Target Architecture Mermaid diagram before asking questions.
3. State important assumptions and proceed without confirmation when they are local, reversible, in scope, and preserve existing public contracts and data compatibility.
4. Pause only when plausible choices would materially change one or more of:
   • system or module boundaries;
   • public APIs, schemas, or compatibility guarantees;
   • persistent data shape or an irreversible migration path;
   • security, privacy, or trust boundaries;
   • user-visible behavior, delivery scope, or operating cost.
5. When pausing, present the recommended target diagram, explain the key tradeoff, and ask no more than three focused decision questions. Do not hand an open-ended architecture problem back to the user.
6. After the decision, update Target Architecture and continue implementation without requesting another approval for the same direction.

Do not require explicit user approval for a target that can be inferred safely. The user should decide material product and architecture tradeoffs, not design the architecture for the agent.

Minimum Sufficient Design

The target is the smallest coherent architecture that satisfies the requested behavior and concrete current constraints. Elegance means fewer concepts, states, branches, dependencies, and ownership boundaries—not cleverness or abstraction density. Do not add modules, components, layers, interfaces, extension points, configuration, schemas, or phases for hypothetical future use.

• Reuse an existing concept or boundary when it can carry the behavior clearly. Add a new one only when required by current behavior, an established repository convention, or a concrete compatibility, security, data-lifecycle, ownership, failure-isolation, deployment, or operational constraint.
• Prefer one implementation path and remove the superseded internal path in the same change. Keep an adapter, feature flag, dual-read/write flow, or other parallel path only for a named compatibility or migration need; record its exit condition and removal step in PLAN.md.
• Preserve public contracts at their boundary; compatibility does not require preserving obsolete internal architecture.
• SPEC.md and PLAN.md describe necessary architecture; they do not justify creating architecture. Omit speculative variants from diagrams and plans.
• Before implementation closes, remove unused indirection, duplicate state or execution paths, obsolete wrappers, and abandoned experiments introduced or exposed by the change.

SPEC.md Requirements

Each substantial SPEC.md should answer:

• What problem does this repository or module solve?
• What is in scope and out of scope?
• What are the main concepts and boundaries?
• What is the current architecture?
• What is the target architecture?
• What data contracts, schemas, APIs, or file layouts matter?
• How does it interact with other modules?

Use this minimum architecture structure:

## Current Architecture

```mermaid
flowchart LR
    subgraph Inputs["Inputs"]
        A["current source"]
    end

    subgraph Runtime["Current Runtime"]
        B["current component"]
    end

    subgraph Outputs["Outputs"]
        C["current artifact"]
    end

    A --> B
    B --> C
```

## Target Architecture

```mermaid
flowchart LR
    subgraph Inputs["Inputs"]
        A["target source"]
    end

    subgraph Runtime["Target Runtime"]
        B["target component"]
    end

    subgraph Outputs["Outputs"]
        C["target artifact"]
    end

    A --> B
    B --> C
```

Keep diagrams simple, horizontal, and truthful. Current Architecture is a map of reality, not a wish. Target Architecture is the current intended design, not an unbounded future vision.

PLAN.md Requirements

Each substantial PLAN.md should answer:

• What is already done?
• What is partially done?
• What is not started?
• What is the recommended next step?
• Who owns each class of work?
• What are the acceptance criteria?
• What risks or open questions remain?
• What verification evidence supports completed items?

Recommended sections:

• Current Status
• Milestones
• Next Steps
• Owners
• Acceptance Criteria
• Verification Log
• Risks / Open Questions
• Status Maintenance Rules

Keeping Docs In Sync

When the implementation changes architecture:

• Update Current Architecture to reflect the new code.
• Update Target Architecture if the intended direction changed or if the old target has been reached.
• Update PLAN.md completed work, remaining work, next steps, risks, acceptance criteria, and verification evidence.

When SPEC.md adds a concept, field, boundary, component, or phase, update PLAN.md so the execution state covers it. When PLAN.md marks work complete, make sure the code, docs, and verification evidence actually support that state.

Working Behavior

Be proactive but respect the gate:

• If the target is clear, implement the change and update docs afterward.
• If the target can be inferred safely, record assumptions, make the smallest necessary SPEC/PLAN update, and implement without waiting for confirmation.
• If the target contains a material architectural fork, do not write production code across that decision. Present a recommended Target Architecture and ask focused questions first.
• If the user explicitly asks only for planning, do not implement code.

This skill is about making architecture a live contract: current reality, target direction, implementation, and plan status should stay aligned.