Itqan — engineering skills suite

إتقان — mastery of the craft.

One resumable orchestrator that runs the full software-engineering lifecycle — spec → plan → build → verify → review → ship — with approval gates you control and evidence required at every step.

Pure Markdown skills for any capable AI runtime (Claude Code, Cursor, Codex, Gemini, …).
It adapts to your stack by reading your repo, never fires on its own, and keeps every
artifact in an engineering/ workspace that survives sessions, machines, and hand-offs.

flowchart LR
    DIS[discover<br/><i>what to build</i>] -. optional .-> DEF
    DEF[define<br/><i>spec / PRD</i>] --> A1{{"👤 approve spec"}}
    A1 --> BP[blueprint<br/><i>ordered task plan</i>] --> A2{{"👤 approve plan"}}
    A2 --> CON[construct<br/><i>TDD build</i>] --> VER[verify<br/><i>prove it works</i>]
    VER --> INS[inspect<br/><i>senior review</i>] --> REL[release<br/><i>GO / NO-GO</i>]
    HAR[harden<br/><i>security audit</i>] -. auth/PII/payments .-> REL
    DES[design<br/><i>UI craft</i>] -. UI tasks .-> DEF
    REL -->|loop mode| DEF

    style A1 fill:#f9e79f,stroke:#b7950b
    style A2 fill:#f9e79f,stroke:#b7950b

📘 The Book — install in depth · first run · every skill's own page · playbooks · conventions · FAQ.

Get started

1 · Install (any agent — Claude Code, Cursor, Codex, and more):

npx skills add saleh-alhaddad/itqan-engineering

2 · Invoke — name it; it never triggers itself:

itqan "add password reset to the auth service"

It scans your repo → asks the questions that matter (each with a suggested answer) → writes
a spec you approve → a plan you approve → builds test-first → proves it → reviews
it → GO/NO-GO. Nothing commits without you.

3 · Resume — days later, even on another machine:

itqan "continue"

It re-validates everything marked done — re-running tests, checking approvals were real —
and picks up at the first unproven step.

Updating, verification, troubleshooting, and clean removal: Book ch. 2.

The skills

The main flow — the idea→ship spine, in order. engineer runs it end to end; each phase
is also invocable on its own.

Shaping — decide before the flow starts.

Audits — judge what already exists.

People

Rule of thumb: know exactly what and it's small → construct · know what, not how →
engineer · don't know what → discover/define · judge something → inspect / design /
assess / harden · prove it → verify · ship it → release.

How you invoke it

This suite never fires on its own — and that is enforced, not requested. Every skill
declares disable-model-invocation: true, so no model can start one; the orchestrator runs
each phase by reading its file, not by triggering it. Words like define and verify turn
up in ordinary requests; the manifest keeps them words.

What you type depends on the install:

⚠️ There is no shell command. The suite ships no executable — it is Markdown an agent
reads. Name the skill inside your AI tool.

What it guarantees

• Two approval gates before code, GO/NO-GO before ship — recorded in a ledger a resumed
  run cannot skip. Say no at a gate and the artifact is revised against your reason,
  never re-presented unchanged.
• Evidence before claims — tests run now, output read, and the count checked: zero
  tests collected is a discovery failure, not a green run.
• Grounded, not guessed — unknown facts are verified with citations, asked, or labeled
  suggestions; time-sensitive facts checked against today's web, not memory.
• Review with no session in its head — inspect and harden declare context: fork
  and rebuild what they need from the workspace, judging what is written, not what you
  meant.
• Never commits, pushes, or writes outward without you — per-file summary + risks +
  suggested message, then it waits. Commit messages never mention the AI.
• Big changes are never big-banged — characterization tests, an ADR, a strangler
  migration, and your explicit approval first.
• Security is a scheduled gate — auth/PII/payments automatically require a harden
  pass; an open Critical always blocks the ship.

What your runtime enforces

Full matrix and what "fallback" means: Book ch. 2.

What it leaves in your project

One ordered workspace — you choose where it lives and who sees it on first run, once:

engineering/
├── profile.md            # how the suite operates here (role, paths, platform)
├── standards.md          # stack, conventions, branch/commit format, domain terms
├── decisions.md          # ADR-style decisions + why
├── index.md              # registry of every task + live status
├── changelog/<feature>/  # the app's memory: dated entry per change
└── tasks/0001-<slug>/    # per task: intake · spec · plan · reviews · summary
    └── state.json        # the phase ledger (status / validated / approved)

Distilled decisions only — never your source pasted verbatim, never raw PII.

Honest limits

• It does not judge whether code is well shaped — measured, not assumed: an A/B on a
  seeded god-function found no difference. Treat review as a floor, not a human reader.
• Approval gates depend on you actually reading — the ledger records that you approved,
  not that you read.
• PRs and tickets are untrusted input — fetched content is treated as data, never as
  instructions; an injection attempt in a diff is reported as a finding. A rule is not a
  guarantee.
• It is version 0.x — conventions still change between versions.

More in the FAQ. Found something broken?
Open an issue with your OS,
shell, the skill, and the literal error text. Contributions: CONTRIBUTING.md.

Articles

Long-form writing on the ideas behind the suite, and on using it in practice:

• Your AI Agent Doesn't Need to Be Smarter. It Needs Discipline. — why capable models still produce unshippable work, and the four rules that fix it. (also on dev.to)

More in the series: one article per skill, each applying it to a real repository.

Repo layout

├── SKILL.md                 ← root router (whole-suite installs)
├── CONVENTIONS.md           ← shared backbone (§1–§20) every skill reads
├── skills/<name>/SKILL.md   ← the 12 skills
├── references/disciplines/  ← stack + concern knowledge packs
├── templates/               ← workspace bootstrap scripts (bash · PowerShell)
├── docs/                    ← 📘 the Book
├── install.sh               ← guided installer
└── .github/                 ← CI: 7 structure guards + executable command tests

MIT — see LICENSE.