techlead

Techlead

A Claude Code plugin that acts as a strict, pragmatic senior developer — enforcing project discipline through 5 core philosophies.

What It Does

Techlead automatically checks your work against five principles:

1. Single Goal — Every project has one goal (GOAL.md). Code that doesn't serve it gets questioned.
2. YAGNI — No speculative abstractions. Write the simplest thing that works.
3. Context-Aware Decisions — Every architectural choice is recorded in an ADR with project-specific reasoning.
4. High Cohesion / Low Coupling — Feature modules don't import each other. Cross-cutting logic goes through core/.
5. Fail Fast — No TODO/FIXME/HACK in committed code. Errors are handled, not swallowed.

See The 5 Philosophies for definitions, rationale, and anti-patterns.

Installation

claude plugin add github:RRoundTable/techlead

Quick Start

After installing, run the init command in any project:

/init-techlead

This creates:

your-project/
├── GOAL.md              # Single project goal + success criteria
├── ROADMAP.md           # Now / Next / Later milestones
├── SPEC.md              # User-observable behaviors + acceptance criteria
├── ARCHITECTURE.md      # Tech stack, module structure, import rules
└── CLAUDE.md            # Updated with Techlead rules

ADRs are stored as git commits with adr/ tags — no file bloat. Discover them via git tag -l "adr/*" and read via git log <tag> --format="%B" -1. Spec records use the same pattern with spec/ tags.

From that point on, Techlead is active. It checks alignment before code changes and verifies quality before commits.

Workflow

Setup

flowchart TD
    A(["/init-techlead"]) --> B{"Existing docs\nfound?"}
    B -- Yes --> C["Ask: overwrite or skip?"]
    B -- No --> D
    C --> D{"Non-standard files\nin docs/?"}
    D -- Yes --> E["Suggest /restructure-docs\nbefore continuing"]
    D -- No --> F
    E --> F["Detect existing source code"]
    F --> G["Interview user\n— goal, success criteria, out of scope,\ncurrent priorities, tech stack"]
    G --> H{"Source code\nfound?"}
    H -- Yes --> I["Scan codebase → derive\nGiven/When/Then specs"]
    I --> J
    H -- No --> J["Generate all files:\nGOAL.md + ROADMAP.md + SPEC.md\nARCHITECTURE.md + CLAUDE.md"]
    J --> K(["Alignment checks are now active"])

After Setup

flowchart TD
    S(["Session starts"]) --> H["SessionStart hook injects\nTechlead workflow + enforcement rules"]
    H --> C(["Day-to-day development"])

    C --> D{"Code change\nrequested?"}
    D -- Yes --> E["check-alignment\nMatches GOAL.md?\nIn ROADMAP Now?\nConforms to SPEC.md?"]
    E -- Aligned --> F["Write / Edit code"]
    E -- Misaligned --> G["Stop — ask user to\nclarify or reprioritize"]
    G --> C

    F --> H2{"User commits?"}
    H2 -- Yes --> I["verify-code-quality\n5 philosophies + spec conformance"]
    I -- Pass --> J(["Commit"])
    I -- Violation --> K["Report file:line + fix"]
    K --> F

    C --> L["/propose-architecture"]
    L --> M["Research + trade-off matrix"]
    M --> N["Recommend with\nproject-specific rationale"]
    N --> O["Record ADR\n(git tag adr/NNN)"]
    O --> C

    C --> P["/propose-spec"]
    P --> Q["Define Given/When/Then\nbehaviors + acceptance criteria"]
    Q --> R["Record spec change\n(git tag spec/NNN)"]
    R --> C

    C --> T["/analyze-architecture"]
    T --> U["Scan codebase → generate\nARCHITECTURE.md with diagrams"]
    U --> C

    C --> V["/read-history"]
    V --> W["Search ADR + spec records\nfrom git tags"]
    W --> C

    C --> X["/restructure-docs"]
    X --> Y["Classify existing docs →\nmigrate to canonical format"]
    Y --> C

How It Works

Skills

Skill	When	What
techlead-workflow	Always active	Sets the pragmatic senior developer tone, philosophy, and skill routing
check-alignment	Before writing/editing code	Verifies the task matches GOAL.md, ROADMAP.md, and SPEC.md
verify-code-quality	Before commits	Checks code against all 5 philosophies + spec conformance
init-techlead	/init-techlead	Bootstrap GOAL.md, ROADMAP.md, SPEC.md, ARCHITECTURE.md, CLAUDE.md
propose-architecture	/propose-architecture or "compare A vs B"	Research, trade-off matrix, recommendation, and ADR recording
propose-spec	/propose-spec or "what should X do?"	Define feature specs as user-observable Given/When/Then behaviors
read-history	/read-history	Search and display ADRs and spec records from git tags
analyze-architecture	/analyze-architecture or "document this project's architecture"	Scan codebase and generate ARCHITECTURE.md with diagrams
restructure-docs	/restructure-docs or "migrate my docs"	Classify existing docs and migrate to canonical format

Hooks