agentleFS
TrecekTrecek/useful-claude-skills/.claude/skills/plan-arc/SKILL.md

plan-arc

Skill1 starsChanged 8 months agoMITView on GitHub

Design the proposed architecture for a task before implementation planning. Use when user says "plan arc", "design architecture", "propose architecture", or wants to define the target system shape before making a plan.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before /make-plan to establish the architectural vision

    line 21
  2. Very specific:

    Before or after /make-req to give requirements a concrete shape to validate against

    line 22
  3. Very specific:

    Create files outside temp/plan-arc/

    line 36
  4. Distinctive:

    Use subagents for parallel exploration of the current codebase

    line 40
  5. Very specific:

    Write to temp/plan-arc/ directory

    line 44
  6. Distinctive:

    Read the task description, requirements document, or user-provided context.

    line 52
  7. Distinctive:

    Follow that skill's conventions for diagram structure and styling

    line 106
  8. Distinctive:

    Every new component is integrated — nothing is introduced but left unconnected

    line 169

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Architecture Design Skill

Design the proposed architecture for a task — what the system should look like when the work is done. Produces a standalone architecture document that requirements can validate against and implementation plans can build from.

When to Use

  • User says "plan arc", "design architecture", "propose architecture"
  • User has a task or requirements and wants to define the target architecture before planning implementation
  • Before /make-plan to establish the architectural vision
  • Before or after /make-req to give requirements a concrete shape to validate against

Core Principles

  • Design the target state. The deliverable is a proposed architecture — what the system should look like after the task is complete. Current architecture is explored as input, not as the output.
  • Architecture is the shape, not the steps. This skill defines what components exist, how they relate, and where boundaries fall. It does not define implementation order, test strategy, or migration steps — that's /make-plan.
  • Multiple lenses when warranted. Different aspects of the task may need different architectural perspectives. Use as many lenses as the task demands — no more, no fewer.
  • Reviewable and refinable. The output is a standalone document meant to be discussed, challenged, and revised before anyone starts planning implementation.

Critical Constraints

NEVER:

  • Modify any source code files
  • Include implementation steps, migration strategies, or test plans
  • Create files outside temp/plan-arc/
  • Diagram systems unrelated to the task

ALWAYS:

  • Use subagents for parallel exploration of the current codebase
  • Ground the proposed design in understanding of what exists today
  • LOAD the /mermaid skill before creating any diagram
  • LOAD each /arch-lens-* skill before creating its diagram
  • Write to temp/plan-arc/ directory

Workflow

Step 1: Understand the Task

Read the task description, requirements document, or user-provided context. Identify:

  • What the task needs to achieve
  • What areas of the system are likely affected
  • What architectural questions the design must answer

Step 2: Explore the Current Architecture

Launch parallel Explore subagents to understand the systems the task will touch:

  • Component boundaries — What modules, services, or packages exist in the affected area?
  • Relationships — How do these components communicate, depend on, or reference each other?
  • Patterns and conventions — What architectural patterns does the existing code follow?
  • Data — What data flows through the affected area? Where is it stored, read, transformed?
  • Extension points — Where does the current architecture anticipate change? Where is it rigid?

The number and focus of subagents depends on the task.

Step 3: Design the Proposed Architecture

Based on the task goals and current system understanding, design the target architecture. Consider:

  • What new components are needed?
  • What existing components need to change?
  • What can remain as-is?
  • Where should boundaries fall?
  • How should new components integrate with existing ones?
  • What patterns from the existing codebase should the design follow or intentionally depart from?

This is the creative step. The design should be the right architecture for the task — not the easiest to implement, not the most conservative change.

Step 4: Select Lenses and Create Diagrams

Choose the architecture lenses that best communicate the proposed design:

If the design involves...Consider Lens
Adding/modifying containers, services, or integrationsC4 Container
Changing workflow logic, state machines, or decision flowProcess Flow
Altering data storage, transformations, or information flowData Lineage
Restructuring modules, changing dependencies, or layeringModule Dependency
Adding/modifying parallel execution or thread handlingConcurrency
Changing error handling, retry logic, or recovery pathsError/Resilience
Modifying repository patterns or data accessRepository Access
Changing CLI commands, config, or monitoringOperational
Adding/modifying validation, trust boundaries, or isolationSecurity
Changing build tools, test framework, or quality gatesDevelopment
Affecting multiple user journeys or cross-component flowsScenarios
Modifying state contracts, field lifecycles, or resume logicState Lifecycle
Changing deployment topology or infrastructureDeployment

For each selected lens:

  1. LOAD the corresponding /arch-lens-* skill using the Skill tool
  2. Follow that skill's conventions for diagram structure and styling
  3. Diagrams show the proposed state — annotate new components with ★ prefix and modified components with ● prefix. Use newComponent class for new elements.

Step 5: Write Output

Save to: temp/plan-arc/arc_{topic}_{YYYY-MM-DD_HHMMSS}.md


Output Template

# Proposed Architecture: {Task/Topic}

**Date:** {YYYY-MM-DD}
**Task:** {Brief description of the task or reference to requirements}

## Summary

{What this architecture proposes and why. What are the key design decisions? How does the proposed system differ from what exists today?}

## Current State

{Brief description of the relevant current architecture — enough context to understand what's changing and why. Not a full system map — just what the reader needs to evaluate the proposal.}

## Proposed Design

### {Lens Name} View

**Question:** {The primary question this lens answers}

{Mermaid diagram showing the proposed state, using ★ for new and ● for modified components}

**Design Rationale:**
- {Why this structure was chosen}
- {What alternatives were considered and why this is preferred}

---

{Repeat for each lens used}

---

## Changes from Current State

| Component | Change | Rationale |
|-----------|--------|-----------|
| {name} | New / Modified / Removed | {Why} |

## Architectural Decisions

{Key decisions embedded in this design and the reasoning behind them. These are the things a reviewer should challenge or confirm.}

## Open Questions

{Decisions that could go either way, areas needing input, or uncertainties that should be resolved before implementation planning.}

Output Quality Checks

Before finalizing, verify:

  • The proposed design addresses the task goals
  • Every new component is integrated — nothing is introduced but left unconnected
  • The design follows existing codebase patterns where appropriate and explicitly justifies departures
  • Diagrams use arch-lens skill conventions with proper ★/● annotations
  • A reader could evaluate whether this is the right architecture without needing to see the codebase
  • Open questions are genuine design decisions, not implementation details

Related Skills

  • /verify-proposed-diag — Verify the proposed architecture diagrams against the codebase. Run after /plan-arc to validate existing components, connection directionality, and integration points.
  • /make-req — Decompose requirements before or after architecture design
  • /make-plan — Create implementation plans from the proposed architecture
  • /mermaid — MUST BE LOADED before creating any diagram
  • /verify-diag — For verifying diagrams that document current state only (no proposed elements)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.