agentic-engineering

A spec-driven workflow for building with coding agents.
Never go prompt → code: shape → decide → execute → measure → eval.

Install · Quickstart · What you get · Plugin reference · Claude Code docs

   shape          decide          execute          verify          diagnose
 ┌─────────┐   ┌─────────┐    ┌──────────┐    ┌───────────┐    ┌──────────┐
 │ /pitch  │──▶│  /adr   │──▶ │  /ship   │──▶ │ /measure  │──▶ │  /eval   │
 │ the spec│   │ the why │    │ the cycle│    │ the data  │    │ the modes│
 └─────────┘   └─────────┘    └──────────┘    └───────────┘    └────┬─────┘
      ▲                                                              │
      └───────────────  flip-criteria · real failures  ◀────────────┘

   readers fan out · one writer at a time · review is a gate · data decides

Contents

• Why this exists
• Install
• Staying updated
• Quickstart
• What you get
• Requirements
• Customize per repo
• Maintaining
• Also in this marketplace
• Contributing
• License

Why this exists

Coding agents make it cheap to go from a prompt straight to a diff — and that's
exactly the trap. Unshaped work balloons in scope, decisions get lost, and a
green build gets mistaken for a correct one.

This plugin encodes a different discipline, distilled from a real, opinionated
agentic-engineering practice: shape the work into a written spec first, record
the hard decisions, delegate execution to a single serialized writer with an
adversarial reviewer as a gate, and let real data — not a passing test — decide
what ships. Five skills, four subagent roles, and verification hooks make that
discipline portable to any repo.

[!NOTE]
These are early, opinionated tools — structurally validated and dogfooded on
this repo, not yet battle-tested across many. Feedback and issues are welcome.
Distributed as a Claude Code marketplace named giusto-agentic; one
marketplace can host many plugins.

Install

In Claude Code:

/plugin marketplace add GiustoPiedimonte/agentic-engineering-marketplace
/plugin install agentic-engineering@giusto-agentic

claude plugin marketplace add GiustoPiedimonte/agentic-engineering-marketplace
claude plugin install agentic-engineering@giusto-agentic

The five commands and four agents become available. New components load on your
next Claude Code session.

Staying updated

Third-party marketplaces don't auto-update by default (a deliberate safety
choice — installed plugins shouldn't change under you silently). Two ways to stay
current with new releases:

• Hands-off (recommended). Enable auto-update for this marketplace once:
  /plugin → Marketplaces → giusto-agentic → toggle auto-update on. Claude
  Code then refreshes it on startup and, when a new version ships, notifies you
  to run /reload-plugins — no manual checking.
• Manual. Pull the latest yourself:

  /plugin marketplace update giusto-agentic
  /plugin update agentic-engineering@giusto-agentic   # and/or github-keeper@…
  

  then /reload-plugins (or restart). The CLI equivalents are claude plugin ….

Releases are versioned — see the releases
and the CHANGELOG.

Quickstart

A typical end-to-end cycle, from idea to merged code:

1. Shape it. /pitch "add Google OAuth to login" — an interview produces
   docs/pitches/oauth.md. Approve the shape before any code is written.
2. Decide it. /clear, then /adr if a consequential choice was made (e.g.
   session strategy). Behavior-altering work records a Flip-criteria.
3. Ship it. /clear, then /ship oauth — the executor implements and opens
   a PR; the reviewer checks the diff against the pitch in a fresh context; you
   fix the real gaps and merge.
4. Prove it. Behavior-altering changes ship dark (flag-OFF), then /measure
   against the recorded criterion flips them on — on real data, not a green build.

[!TIP]
Run /clear between stages. Separating exploration, decision, and execution
into clean contexts is the single biggest lever on output quality.

What you get

Skills — slash commands

Agents — roles

The organizing law is parallelize readers, serialize writers: research and
review fan out across many agents; only one writer ever touches the code.

Hooks

• PostToolUse — auto-format/lint edited TS/Py files (only if eslint/ruff are present).
• Stop — an advisory reminder: when a turn leaves uncommitted changes, it
  prints a one-line nudge to run the project's own checks before declaring done.
  It never blocks and never re-invokes the model (so it can't loop, even with
  background workflows); it's silent when the tree is clean.

[!NOTE]
The Stop hook is a reminder, not a gate — it surfaces "you have uncommitted
changes; run this project's checks and show the output" and then gets out of the
way. The real verification discipline lives in the /ship and executor prompts;
the hook just keeps it front-of-mind without ever blocking the turn.

Requirements

• Claude Code (CLI, desktop, or IDE extension).
• jq on your machine, for the format hook.
• (optional) A docs MCP such as Context7
  so researcher / /measure can pull live library docs:
  claude mcp add context7 -- npx -y @upstash/context7-mcp.

Customize per repo

The skills reference docs/pitches/ and docs/DECISIONS.md by convention. Adapt
the doc-bundle tiers in
EXECUTION_PLAYBOOK.md
and the invariants in the review checklist to your project, and change the paths
if your repo differs. See the plugin reference
for the full component breakdown.

Maintaining

Releasing an update: bump version in both
plugin.json and
marketplace.json, commit, tag, and push.
Users pick it up with /plugin marketplace update giusto-agentic.

Validate before pushing:

claude plugin validate .
claude plugin validate ./plugins/agentic-engineering

agentic-engineering-marketplace/
├── .claude-plugin/
│   └── marketplace.json        # lists the plugin(s), schema-validated
├── assets/
│   └── banner.svg
├── plugins/
│   └── agentic-engineering/    # the plugin itself
│       ├── .claude-plugin/plugin.json
│       └── skills/  agents/  hooks/  README.md
├── LICENSE
└── README.md

Also in this marketplace

github-keeper — make a public repo
well-made and honest. /readme audits and elevates the README (honest clickable
badges, repo-specific banner and chips, cognitive-funnel structure); /opensource
adds the community-health files, an honest CI gate, and the right repo settings.
Install it with /plugin install github-keeper@giusto-agentic.

Contributing

Issues and PRs are welcome — bug reports, a sharper skill prompt, or a new
role/skill that fits the shape → decide → execute → measure → eval spine.
Open an issue
to discuss anything non-trivial first. Run claude plugin validate . before
opening a PR.

License

MIT © Giusto Piedimonte