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:
  copy

  /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