Pulumi Blog: Codex

10 tips to improve your coding agent game

Engin Diri — Mon, 21 Sep 2026 00:00:00 +0000

In May I told you to trim the root instruction file until it fits on one screen. I also said anything that needs a hard guarantee belongs in a hook. In June I argued that the model that wrote the code shouldn’t be the one grading it. Several papers published this summer tested related questions.

Most of the findings support that advice, while the research on subagent costs calls for more caution. Below are ten tips for working with any coding agent. Each one is checked against what the research measured, which is sometimes narrower than the abstract suggests.

Instructions kept only in chat can disappear during summarization. Nearly every fix below moves something out of the chat and into a file, a hook, a test, or a fresh session. That’s what I meant in June by “the agent forgets, the repo does not.”

Agent instructions

1. Write for the agent, not for a new hire

A new hire can ask a teammate what a vague convention means. An agent may proceed with an interpretation you never intended. Anthropic’s docs on project instructions ask for instructions “concrete enough to verify,” like “API handlers live in src/api/handlers/” instead of “Keep files organized.”

One line in my own Go instructions says to wrap errors with fmt.Errorf("...: %w", err) and never discard one silently. An agent can follow that, and a reviewer can check it. Try doing either with “handle errors properly.”

The instruction file is also where agents look first. A Peking University study by Zhijun Gao and Jing Chen traced 557 real agent sessions and sorted every documentation touch. Instruction files and the agents’ own working notes made up 60.5% of them, and API references only 1.3%. The authors couldn’t show that any particular writing style changes behavior. Most of their sessions also came from Claude Code, so the style question is still open.

2. Treat agent instructions like code, because they rot

Specific instructions go stale. Rename a folder or swap a database, and the file keeps describing a codebase that no longer exists. The agent then has two options: burn turns reconciling the two, or believe the file.

How often does that happen? Christoph Treude and Sebastian Baltes ran an existing documentation checker, DOCER, unchanged over 612 agent config files from 356 randomly sampled GitHub repositories. In close to one in four of those repositories, a file named a function, path, or script that had since vanished from the code.

The authors call the number a feasibility signal rather than a precise rate. That’s fair, since only 32 of the 50 flags they checked by hand were real. A second paper explains why rot piles up. Across 441 repositories, 73.8% of AI configuration files were committed once and never touched again.

A crude version of the check ran in September against the AGENTS.md of the repository this blog is built from. It flagged 37 of 124 path-like references. Nearly all were noise, mostly relative paths and files that live in other repositories. One wasn’t. Since a dark mode change in June, the file had been pointing agents at a docs-logo.html partial that was never added to the repository.

The authors suggest running the check in CI, and DOCER already has a GitHub Actions version. In May I described a Stop hook that drafts instruction-file updates at the end of every session. It catches drift while the diff is still small. Either works if a human reads what it flags.

3. Keep AGENTS.md short, but don’t delete it

The mistake I see most often is a root AGENTS.md that has grown into a small book loaded into every session. Anthropic’s docs for Claude Code set a target of under 200 lines per file, because “longer files consume more context and reduce adherence.” Codex stops reading AGENTS.md files once they add up to 32 KiB by default. Since v2.1.277, Claude Code reads AGENTS.md directly as well, so one short file can now brief both agents.

The cleanest measurement of that cost comes from outside coding. Lodha and colleagues at Microsoft followed a GPT-5 agent that itemizes hotel expenses. They trimmed the tool-call history it carried from step to step down to the last five calls. Completion went up from 71.0% to 79.0%, and the agent used 63.9% fewer tokens doing it.

Closer to home, a team from ETH Zurich and LogicStar.ai tested context files with Claude Code, Codex, and Qwen Code. The files didn’t measurably help. Neither the generated nor the developer-written ones produced a statistically significant gain in task success. The generated ones also raised inference cost by 20% or more.

Don’t delete the file, though. Denisov-Blanch and colleagues followed 509 open-source repositories after they adopted coding agents. Among the agent-first ones, those with no committed AI configuration saw cognitive complexity grow 53%. The ones with at least an instruction file grew 27%. The authors call that hypothesis-generating rather than causal.

It’s still a good reason to keep the file and prune it instead. Anthropic’s best practices suggest one question for every line: “Would removing this cause Claude to make mistakes? If not, cut it.” Whatever survives the cut but only matters for some tasks belongs in skills or subdirectory files that load when the work gets there.

Long sessions

4. Don’t let /compact carry your instructions

When a session gets long, /compact is the obvious move: summarize, free up the window, keep going. The research says to watch what you let it summarize.

A University of Passau team ran real agent config files through several compactors, including Claude Code’s /compact on Sonnet 4.6. The prompt asked them to keep every safety instruction verbatim. After five rounds in a row, each halving the text, 10% of the safety instructions were left. After just one round, 53% survived, despite the prompt asking to preserve them all.

Shiyang Chen measured what agents do afterwards. Across seven models, one compaction raised policy violations from 0% to 30%, and to 59% for the worst two.

Where the policy lived decided most of it. Policies in a preserved system message held. The same policies given as a standing user instruction, a memory entry, or tool output decayed by 33 to 50 points. For DeepSeek-V4, a compacted policy did worse than no policy at all. The summary kept the pending task and dropped the policy that constrained it.

Claude Code handles part of this for you. After /compact, it re-injects its project-root instruction file from disk. Anything you only typed into the chat gets summarized with the rest. AGENTS.md isn’t on that list, so if your instructions live there, a SessionStart hook that matches compact is the documented way to put them back.

Summaries aren’t useless. The expense agent from tip 3 did best, at 91.6%, when a summary replaced the tool calls it dropped. Summaries are fine for the trail of what happened.

The better habit is to keep each task small enough that the session never needs compacting. Anthropic’s best practices already say to run /clear between unrelated tasks. When a task runs long anyway, a handoff note you write yourself beats a summary you can’t inspect. In August I wrote that prompt guardrails degrade with context length, and compaction is one way that happens.

5. Use hooks for what must always happen

An instruction in a markdown file is a request. The model honors it most of the time. That’s fine for naming conventions, and not fine for anything that has to happen every time. Ask an agent to run the tests before it finishes and it usually will. A Stop hook runs them every time and hands the failures back. Claude Code’s hooks guide calls that “deterministic control: certain actions always happen rather than relying on the LLM to choose to run them.”

Chen’s fix points the same way: pinning the policy outside the summary took about 47 tokens and brought violations back to 0%. A hook goes further still. It never enters the context, so compaction has nothing to drop. For infrastructure, Pulumi Policies plays that role at deploy time: a mandatory policy blocks a noncompliant deployment, whatever the agent was told.

My own setup has two small guardrail hooks. One blocks destructive shell commands, and the other scans every edited file for secrets. While I was working on this post, rtk, a PreToolUse hook I use to compress command output, collided with Claude Code’s worktree isolation check. Every git command in the session was refused until I called git by its full path. That’s the behavior you want for the checks that matter, and a good reason to keep the list of hooks short.

6. Don’t switch to a bigger model mid-task

When a session goes sideways, it’s tempting to type /model, pick the bigger one, and keep going. Keeping the same transcript can carry earlier mistakes into the stronger model’s attempt. Drew Breunig describes this as context poisoning: an error “makes it into the context, where it is repeatedly referenced.”

This tip has the strongest paper on the list. A group at AWS ran all 500 SWE-bench Verified tasks with a cheap model that hands over to a strong one partway through. They tested Claude Haiku 4.5 to Opus 4.7 plus a GPT pair, across 58,000 runs. Handing over the full transcript recovered 47% of the gap between the two Claude models and 36% for GPT. It also cost more: $1.61 a task, against $0.72 for starting with Opus. Restarting Opus from scratch, even after paying for Haiku’s wasted attempt, came to $0.90 and solved more.

When they dropped the transcript and kept only the file edits on disk, recovery climbed to 64% for Claude and 84% for GPT. If the task needs the big model, start with it. If you’re already halfway in, write down what’s done and where it’s stuck. Then open a new session on the stronger model, and point it at that note and the working tree.

Parallel agents

7. Count the tokens your subagents burn

Parallel agents burn tokens fast. Anthropic’s write-up of its multi-agent research system puts rough numbers on it. Agents use about 4× the tokens of a chat. Multi-agent systems use about 15×. The same post notes that most coding tasks parallelize less well than research does. Claude Code’s cost docs put agent teams at roughly 7× the tokens of a standard session when teammates run in plan mode.

The newer multi-agent features cost more too. Claude Code’s docs say a dynamic workflow “can use meaningfully more tokens than working through the same task in conversation.” Claude Code warns when a run schedules more than 25 agents or its projected token total passes 1.5 million. Even a message sent through cross-session messaging “counts toward usage like a prompt you type.”

The cost figures qualify my earlier advice. In May I told you to use the Explore subagent liberally, and for exploration I still would. A subagent that reads forty files to find the three that matter keeps all forty out of your main session.

On Claude subscription plans, /usage now breaks recent usage down by subagents, skills, plugins, and MCP servers, so you can see where it went. I prefer to decide which tasks get delegated before the agent starts spawning helpers. In the parallel coding playbook, the parallelism came from issues a human wrote, and that’s how I’d keep it.

8. Skip the coordinator agent

The team-lead pattern is tempting. One agent assigns the work, the others report back and message each other, and you get to watch it all happen. Claude Code’s own agent teams are still “experimental and disabled by default,” and the research gives a reason not to rush. Dynamic workflows sit alongside agent teams rather than replacing them. Cross-session messaging is for your separate sessions, not a supervised team.

Giuseppe Destefanis and Tomaso Aste at UCL tested the cheapest kind of coordinator: a prompt that names one agent the lead. Their sample covered 1,902 graded Claude Code runs, with teams of one to sixteen agents. The coordinator created no communication hub and no reliable improvement.

The failure worth remembering came from an eight-step invoice pipeline, which worked in nine of ten runs with two or four agents. With eight, one agent per step, it failed all ten. Every failure sat on the same seam: whether to round at each step or once at the end. The agents discussed rounding in all ten runs. It didn’t help. As the authors put it, “Talking more did not close an interface that nobody owned.”

The tasks were synthetic Python, and the coordinator was only a prompt label. Still, Walden Yan at Cognition described the mechanism in 2025: “Actions carry implicit decisions, and conflicting decisions carry bad results.” The rounding failure is a clean example of that.

A main agent that hands out self-contained tasks and collects the results is enough. Give every interface between those tasks an owner, and write the contract into a file. That’s what stood out in GSD when I compared orchestration frameworks in April: its orchestrator never touches source files. Dynamic workflows push the same idea further. In the docs’ words, “a workflow moves the plan into code,” so no lead agent has to hold it in its context.

Checking the work

9. Plan the checks first, and keep the writer out of them

Two habits belong together here. Decide before the first line of code how the work gets checked. Pick the tools the agent uses to test itself, the tests it writes, and the command that proves the build. Know what you’ll look at when it says it’s done.

The second habit is to never let the model that wrote the code approve it. Anthropic’s best practices call this a writer/reviewer pattern. Their reason: “a fresh context improves code review since Claude won’t be biased toward code it just wrote.”

The best measurement comes from an unusual source: an evaluation of Leni, an AI business analyst. The company that builds Leni wrote it, and the results come from single runs, so read it with that in mind. Of the agent’s 11-point gain on SpreadsheetBench Verified, scaffolding and prompting account for 9.5. The verification loop added the last 1.5 by rescuing six tasks, but only two when the model that produced the output did the checking.

The code repair study in the next tip saw the same thing from the other side. Left to decide on its own when to stop, the model accepted 99.8% of its answers, and 29.5% of what it accepted was wrong. A gate on the visible tests cut that to 2.4%.

Run the tests and build before review, then review the change in a fresh session.

10. Stop revising once it passes

An Alibaba Cloud team tested repeated revision by forcing three revisions on each of 30 HumanEval repair tasks with a 7-billion-parameter open model. With test traces as feedback, 82.0% of runs were correct after the first revision. The second revision knocked that down to 67.3%, and the third only brought it back to 69.3%. About 85% found a correct patch at some point along the way, while about one in six found one and then lost it. With plain pass-or-fail feedback, 8.0% found a correct patch and then lost it.

Test output from an older version of the code was one source of mistakes. In one task, the model read a stale report from a version with a Caesar shift of 12. It then changed the correct shift of 4 back to 12, in every seed.

The study used a small model, but the precautions are straightforward. Commit the moment the tests pass, so there’s a last-known-good version to go back to. Rerun the tests on the current code before each revision instead of feeding back output from three edits ago. Set a retry limit for fixes that keep failing.

Where to start

If you have one afternoon, go in this order:

Run a drift check on every AGENTS.md you have. Read what it flags yourself.
Cut the root file to what’s specific and true. Move the rest into skills or subdirectory files.
Move one must-run step into a hook. For most teams, that’s running the tests.
Restart instead of compacting or escalating. Write the handoff note yourself.
Commit on green, and review in a separate session.

Check infrastructure changes before they ship

For infrastructure code, pulumi preview gives an agent a deterministic diff to check, and a mandatory policy blocks a noncompliant deployment. Wire those checks into Claude Code, Codex, Cursor, or Pulumi Neo with Agent Skills and the Pulumi MCP server.

Get started

Start by checking the paths and commands in your root AGENTS.md. Fix anything stale, then remove instructions the agent doesn’t need.

Superpowers, GSD, and GSTACK: Picking the Right Framework for Your Coding Agent

Engin Diri — Mon, 13 Apr 2026 00:00:00 +0000

Three community frameworks have emerged that fix the specific ways AI coding agents break down on real projects. Superpowers enforces test-driven development. GSD prevents context rot. GSTACK adds role-based governance. All three started as Claude Code plugins and now reach across Codex, Cursor, Windsurf, Gemini CLI, OpenCode, and half a dozen other agents.

Pulumi uses general-purpose programming languages to define infrastructure. TypeScript, JavaScript, Python, Go, .NET, Java. Every framework that makes AI agents write better TypeScript also makes your pulumi up better. After spending a few weeks with each one, and revisiting them again as the space moved, I have opinions about when to use which.

The problem these orchestration frameworks solve

AI coding agents are impressive for the first 30 minutes. Then things go sideways. The patterns are predictable enough that three separate teams independently built agent orchestration frameworks to fix them:

Context rot. Every LLM has a context window. As that window fills up, earlier instructions fade. You start a session asking for an S3 bucket with AES-256 encryption, proper ACLs, and access logging. Two hours and 200K tokens later, the agent creates a new bucket with none of those requirements. The context window got crowded and your original instructions lost weight.

No test discipline. Agents write code that looks plausible. Plausible code compiles. Plausible code even runs, for a while. But plausible code without tests is a liability. The agent adds a feature and quietly breaks two others because nothing verified the existing behavior was preserved.

Scope drift. You ask for a VPC with three subnets. The agent decides you also need a NAT gateway, a transit gateway, a VPN endpoint, and a custom DNS resolver. Helpful in theory. In practice, you now have infrastructure you never requested and barely understand. You will also pay for it monthly.

These problems aren’t specific to Claude Code or any particular agent; they happen with Cursor, Codex, Windsurf, and every other LLM-powered coding tool. The context window doesn’t care which name is on the wrapper.

That’s where agent-orchestration frameworks come in. In a single-agent workflow, the agent uses one continuous conversation to hold the whole project in its head. With an orchestration framework, the agent decomposes work into phases, enforcing tests or reviews along the way, handing state between context windows, and dispatching subagents for isolated tasks. Superpowers, GSD, and GSTACK are the three most widely adopted frameworks that do this.

Superpowers: What does it do, and who is it for?

Superpowers enforces a strict rule: no production code gets written without a failing test first. Superpowers was created by Jesse Vincent and has grown to roughly 279K GitHub stars.

The framework enforces a 7-phase workflow. Brainstorm the approach. Write a spec. Create a plan. Write failing tests (TDD). Spin up subagents to implement. Review. Finalize. Every phase has gates. You cannot skip ahead. The iron law is that production code only exists to make a failing test pass.

This sounds rigid. It is. That is the point.

Superpowers includes a Visual Companion for design decisions, which helps when you are making architectural choices that need visual reasoning. The main orchestrator manages the entire workflow from a single context window, delegating implementation work to subagents that run in isolation.

The tradeoff is that the mega-orchestrator pattern means the orchestrator itself can hit context limits on very long sessions. One big brain coordinating everything works well until the big brain fills up. For most projects, this is not an issue. For marathon sessions with dozens of files, keep it in mind.

The workflow breaks down into skills that trigger automatically:

Skill	Phase	What it does
`brainstorming`	Design	Refines rough ideas through Socratic questions, saves design doc
`writing-plans`	Planning	Breaks work into 2-5 minute tasks with exact file paths and code
`test-driven-development`	Implementation	RED-GREEN-REFACTOR: failing test first, minimal code, commit
`subagent-driven-development`	Implementation	Dispatches fresh subagent per task with two-stage review
`requesting-code-review`	Review	Reviews against plan, blocks progress on critical issues
`finishing-a-development-branch`	Finalize	Verifies tests pass, presents merge/PR/keep/discard options

The results are worth citing carefully. chardet 7.0’s own performance docs show it running 41x faster than chardet 6.0.0 (494 files/sec versus 12). Maintainer Dan Blanchard wrote about rewriting chardet from scratch with Claude, delegating implementation work to subagents — but his post never names Superpowers, and it’s mostly about whether the result counts as a derivative work. Take the 41x figure as verified; take “built with Superpowers specifically” as unconfirmed.

Superpowers now reaches well beyond Claude Code: Antigravity, Codex App, Codex CLI, Cursor, Devin CLI, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build CLI, Kimi Code, OpenCode, Pi, and Hermes Agent are all in its current install list.

GSD: How does it prevent context rot?

GSD prevents context rot by keeping the orchestrator out of the work: your main session spawns a fresh-context subagent for each research, planning, execution, and verification task, then collects results instead of accumulating them. GSD (Get Shit Done) was created by Lex Christopherson, known online as TÂCHES.

The key architectural decision: the orchestrator never touches source files. Because it only spawns agents, collects their results, and updates shared state on disk, its own context window grows slowly and predictably, while each spawned agent starts with a clean window scoped to exactly one task. Phase state lands in .planning/ as durable files, so the next step reads artifacts rather than conversation history.

Think about why this matters. When the orchestrator also writes the code, your 200K token context window is a shared resource. Instructions from hour one compete with code from hour three. GSD sidesteps this entirely, because the orchestrator’s job is dispatch and bookkeeping, not implementation. GSD also includes quality gates that detect schema drift and scope reduction. If the agent starts cutting corners or wandering from the plan, the gates catch it.

Editor’s note: Since this post was first published, GSD’s original repository, gsd-build/get-shit-done, was archived by its owner on June 26, 2026 with 64.6K stars frozen in place. Development continues in the Open GSD organization as GSD Core, currently at roughly 8.8K stars and installed via npx @opengsd/gsd-core@latest.

The tradeoff: GSD has more ceremony than the other two frameworks. For a quick script or a single-file change, the phase-based workflow is overkill. GSD earns its keep on projects that span multiple files, multiple sessions, or multiple days.

The core commands map to a phase-based workflow:

Command	What it does
`/gsd-new-project`	Full initialization: questions, research, requirements, roadmap
`/gsd-onboard`	Onboard an existing codebase instead of starting greenfield
`/gsd-discuss-phase`	Capture implementation decisions before planning starts
`/gsd-plan-phase`	Research, plan, and verify for a single phase
`/gsd-execute-phase`	Execute all plans in parallel waves, verify when complete
`/gsd-verify-work`	Manual user acceptance testing
`/gsd-ship`	Create PR from verified phase work with auto-generated body

GSD Core’s installer supports Claude Code, OpenCode, Antigravity CLI, Kimi CLI, Kilo, Codex, Copilot, Cursor, and Windsurf, and prompts you for which one at install time.

GSTACK: What does role-based governance buy you?

GSTACK buys you a division of labor: instead of one agent trying to hold product, engineering, QA, and security judgment simultaneously, it splits the work across 23 specialist roles, each with its own scope and constraints. GSTACK was created by Garry Tan (President and CEO of Y Combinator) and has grown to roughly 130K stars.

The framework enforces five layers of constraint. Role focus keeps each specialist in their lane. Data flow controls what information passes between roles. Quality control gates ensure standards at handoff points. The “boil the lake” principle means each role finishes what it can do perfectly and skips what it cannot, rather than producing mediocre work across everything. And the simplicity layer pushes back against unnecessary complexity.

The role isolation is what makes GSTACK distinctive. The engineer role does not see the product roadmap. The QA role does not see the implementation details. Each role only receives the context it needs to do its job. This is not just about efficiency. It prevents the kind of scope creep where an agent that knows everything tries to do everything.

“Boil the lake” is my favorite principle across all three frameworks. It is the opposite of how most agents work. Agents default to attempting everything and producing something mediocre. GSTACK says: do fewer things, but do them right.

The tradeoff: 23 specialist roles feels heavy for pure infrastructure work. If you are writing Pulumi programs and deploying cloud resources with component resources, you probably do not need a product manager role or a designer role. GSTACK shines when you are building a product, not just provisioning infrastructure.

Each slash command activates a different specialist:

Command	Role	What it does
`/office-hours`	YC partner	Six forcing questions that reframe your product before you write code
`/plan-ceo-review`	CEO	Four modes: expand scope, selective expand, hold, reduce
`/plan-eng-review`	Engineering manager	Lock architecture, map data flow, list edge cases
`/review`	Staff engineer	Find bugs that pass CI but break in production, auto-fix the obvious ones
`/qa`	QA lead	Real Playwright browser testing, not simulated
`/ship`	Release engineer	One-command deploy with coverage audit
`/cso`	Security officer	OWASP and STRIDE security audits

GSTACK’s Codex support is the most deliberate of the three: setup reads the model field from your ~/.codex/config.toml and generates a matching behavioral profile automatically, so the role constraints adapt to the specific Codex model you are running. It also supports Claude Code, OpenCode, Cursor, Factory Droid, Slate, Kiro, and Hermes.

Superpowers, GSD, or GSTACK: Which one’s the best fit for you?

None of these is universally best. Knowing your failure mode is the real decision.

	Superpowers	GSD	GSTACK
What it locks down	The dev process itself	The execution environment	Who decides what
Orchestration	Single orchestrator	Per-phase orchestrators	23 specialist roles
Context management	One window	State-to-disk, fresh per phase	Role-scoped handoffs
Where it shines	TDD, subagent delegation, disciplined plan execution	Marathon sessions, parallel workstreams, crash recovery	Product strategy, multi-perspective review, real browser QA
Where it struggles	Anything beyond the build phase	Overkill for small tasks, no role separation	The actual writing-code part
Best for	Solo devs who need test discipline	Complex projects that span days or weeks	Founder-engineers shipping a product
GitHub stars (current)	~279K	~8.8K on the new repo (plus 64.6K on the archived original)	~130K
Agent support	13+ agents	9+ agents via installer	8+ agents

For infrastructure work, GSD’s context management matters most. Long Pulumi sessions that provision dozens of resources across multiple stacks are exactly the scenario where context rot bites hardest. GSD’s phase-based approach keeps each orchestrator fresh. If you would rather not manage that context yourself, Pulumi Neo is an infrastructure agent that starts from your stacks, dependencies, and deployment history.

Superpowers’ TDD workflow maps well to application code where unit tests are straightforward. Infrastructure testing is different. You cannot unit test whether an IAM policy actually grants the right permissions. You can test the shape of the policy with Pulumi’s testing frameworks, but the real validation happens at pulumi preview and pulumi up. Superpowers still helps here (discipline is discipline), but the TDD cycle is less natural for infra than for app code.

GSTACK shines when the project has product dimensions. If you are building a SaaS platform where the infrastructure serves a product vision, GSTACK’s multi-role governance keeps the product thinking connected to the engineering work. For pure infra provisioning, the extra roles add overhead without much benefit.

What keeps going wrong	Try this	The reason
Code works today, breaks tomorrow	Superpowers	Forces every change through a failing test first
Quality drops after the first hour	GSD	Fresh context per phase, nothing carries over
You ship features nobody asked for	GSTACK	Product review before engineering starts
All of the above	GSTACK for direction, bolt on Superpowers TDD	No single framework covers everything yet

Point your coding agent at Pulumi

Whichever framework and agent you run, Pulumi defines infrastructure in TypeScript, Python, and Go, so your agent generates cloud resources it already knows how to write.

Get started

Do Superpowers, GSD, and GSTACK work with Codex?

Yes, all three now support OpenAI’s Codex, though the depth of that support varies. Superpowers ships two separate Codex integrations distributed through the official OpenAI plugin marketplace; GSTACK goes furthest by detecting your specific Codex model and generating a matching behavioral profile; GSD’s installer offers Codex as one of several supported runtimes without Codex-specific tuning.

Framework	Codex support	How it works
Superpowers	Native, dual-mode	Separate “Codex App” and “Codex CLI” integrations, both installed through the official Codex plugin marketplace
GSD (GSD Core)	Native, generic	The `npx @opengsd/gsd-core@latest` installer lists Codex as a supported runtime alongside Claude Code, Cursor, and others
GSTACK	Native, model-aware	`./setup --host codex` installs to `~/.codex/skills/gstack-*/` and reads your Codex model from `config.toml` to tune role behavior automatically

Codex support has deepened noticeably since this post first ran. All three frameworks now treat it as a first-class target rather than one more name in an install matrix.

What are the alternatives to Superpowers, GSD, and GSTACK?

The most talked-about alternative right now is Everything Claude Code (ECC), built by Affaan Mustafa. Where Superpowers, GSD, and GSTACK each impose one opinionated methodology, ECC takes the opposite approach: a large pre-built bundle of subagents, skills, hooks, and commands — dozens of the first, hundreds of the second — plus a security layer called AgentShield. It works best with Claude Code today, has a supported Codex sync path, and offers capability-limited adapters for Cursor and OpenCode, so check its support-status matrix before assuming feature parity across agents. It has grown large enough that community threads now debate “ECC vs. Superpowers” the same way they debate the three frameworks above. Choose ECC if you want breadth and are willing to pick your own process; choose one of the three above if you want the process itself enforced.

Also worth knowing: wshobson/agents positions itself as a plugin marketplace rather than a single framework, aggregating dozens of agents, skills, and commands that install natively through Claude Code’s plugin system. It is less a competitor to Superpowers, GSD, or GSTACK than a different shelf in the same store.

You can also roll your own. Claude Code’s native subagents, hooks, and skills now cover a meaningful slice of what these frameworks automate, including asynchronous subagent execution that used to require a third-party context-management layer. If your needs are narrow, a CLAUDE.md file plus a couple of custom skills may get you 80% of the value without adopting a whole framework.

For infrastructure specifically, there is also the managed-agent route rather than the framework route — see the note on Pulumi Neo at the end of this post.

How do these frameworks work with Pulumi?

These frameworks solve the “how” of agent orchestration. Skills (like the ones from Pulumi Agent Skills) solve the “what,” teaching agents the right patterns for specific technologies. Frameworks and skills complement each other. A skill tells the agent to use OIDC instead of hardcoded credentials. A framework makes sure the agent still remembers that instruction 200K tokens later. This works because Pulumi infrastructure is real code: an agent operating under Superpowers’ TDD gates or GSD’s phase boundaries can test, refactor, and version infrastructure the same way it does application code, which a declarative config format does not give it room to do.

GSD’s state-to-disk approach pairs naturally with Pulumi stack outputs. Each phase can read the previous phase’s stack outputs from the state files, so a networking phase can provision a VPC and the compute phase can reference the subnet IDs without any context window gymnastics.

Superpowers’ TDD cycle maps to infrastructure validation. Write a failing test (the expected shape of your infrastructure). Run pulumi preview (red, the resources do not exist yet). Run pulumi up (green, the infrastructure matches the test). This is not a perfect analogy since infrastructure tests are broader than unit tests, but the discipline of “verify before moving on” translates directly.

You do not have to pick one framework and commit forever. Try GSD for a long multi-stack project. Try Superpowers for a focused library. See which failure mode bites you most and let that guide your choice.

How do you install and get started?

github.com/obra/superpowers

github.com/open-gsd/gsd-core

github.com/garrytan/gstack

All three frameworks support multiple agents. For Claude Code, the current install commands are:

# Superpowers
/plugin install superpowers@claude-plugins-official

# GSD Core (installer asks which agent and whether to install globally or locally)
npx @opengsd/gsd-core@latest

# GSTACK
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup

If you have an old GSD install pointed at get-shit-done-cc, switch to @opengsd/gsd-core; the original repository is archived and will not receive further updates. Check each repository’s README for Codex, Cursor, Windsurf, and other agent-specific instructions.

If you want a managed experience that handles orchestration for you, Pulumi Neo is grounded in your actual infrastructure, not internet patterns. It understands your stacks, your dependencies, and your deployment history. The 10 things you can do with Neo post shows what that looks like in practice.

Pick one and give it a project. You will know within an hour whether it fixes your particular failure mode.

Try Pulumi for Free

Pulumi Agent Skills: Best practices and more for AI coding assistants

Pulumi Neo Team — Thu, 29 Jan 2026 00:00:00 +0000

AI coding assistants have transformed how developers write software, including infrastructure code. Tools like Claude Code, Cursor, and GitHub Copilot can generate code, explain complex systems, and automate tedious tasks. But when it comes to infrastructure, these tools often produce code that works but misses the mark on patterns that matter: proper secret handling, correct resource dependencies, idiomatic component structure, and the dozens of other details that separate working infrastructure from production-ready infrastructure.

We built Neo for teams that want deep Pulumi expertise combined with organizational context and deployment governance. But developers have preferred tools, and we want people to succeed with Pulumi wherever they work. Some teams live in Claude Code. Others use Cursor, Copilot, Codex, Gemini CLI, or other platforms. That is why we are releasing Pulumi Agent Skills, a collection of packaged expertise that teaches any AI coding assistant how to work with Pulumi the way an experienced practitioner would.

What are agent skills?

Skills are structured knowledge packages that follow the open Agent Skills specification. They work across multiple AI coding platforms including Claude Code, GitHub Copilot, Cursor, VS Code, Codex, and Gemini CLI. When you install Pulumi skills, your AI assistant gains access to detailed workflows, code patterns, and decision trees for common infrastructure tasks.

Available Pulumi skills

We are launching a set of skills organized into two plugin groups: authoring and migration. You can install all skills at once or choose specific plugin groups based on your needs.

Authoring skills

This plugin includes four skills focused on code quality, reusability, and configuration.

Pulumi best practices encodes the patterns that prevent common mistakes. It covers output handling, component structure, secrets management, safe refactoring with aliases, and deployment workflows. The skill flags anti-patterns that can cause issues with preview, dependencies, and production deployments.
Pulumi Component provides a complete guide for authoring ComponentResource classes. The skill covers designing component interfaces, multi-language support, and distribution. It teaches assistants how to build reusable infrastructure abstractions that can be consumed from any Pulumi language.
Pulumi Automation API covers programmatic orchestration of Pulumi operations. The skill explains when to use Automation API versus the CLI, the tradeoffs between local source and inline programs, and patterns for multi-stack deployments.
Pulumi ESC covers centralized secrets and configuration management. The skill guides assistants through setting up dynamic OIDC credentials, composing environments, and integrating secrets into Pulumi programs and other applications.

Migration skills

Convert and import infrastructure from other tools to Pulumi. This plugin includes four skills covering complete migration workflows, not just syntax translation.

Terraform to Pulumi walks through the full migration workflow. It handles state translation, provider version alignment, and the iterative process of achieving a clean pulumi preview with no unexpected changes.
CloudFormation to Pulumi covers the complete AWS CloudFormation migration workflow, from template conversion and stack import to handling CloudFormation-specific constructs.
CDK to Pulumi covers the complete AWS CDK migration workflow end to end, from conversion and import to handling CDK-specific constructs like Lambda-backed custom resources and cross-stack references.
Azure to Pulumi covers the complete Azure Resource Manager and Bicep migration workflow, handling template conversion and resource import with guidance on achieving zero-diff validation.

How to install

Claude Code plugin marketplace

For Claude Code users, the plugin system provides the simplest installation experience:

claude plugin marketplace add pulumi/agent-skills
claude plugin install pulumi-authoring # Install authoring skills
claude plugin install pulumi-migration # Install migration skills

You can install both plugin groups or choose only the ones you need.

Universal installation

For Cursor, GitHub Copilot, VS Code, Codex, Gemini, and other platforms, use the universal Agent Skills CLI. The universal installer does not read plugin marketplace manifests, so install each end-user skill group:

npx skills add pulumi/agent-skills/pulumi --skill '*'
npx skills add pulumi/agent-skills/migration --skill '*'
npx skills add pulumi/agent-skills/delegation --skill '*'

This works across all platforms that support the Agent Skills specification.

Using skills

Once installed, skills activate automatically based on context. When you ask your assistant to help migrate a Terraform project, it draws on the Terraform skill’s workflow. When you are debugging why resources are being recreated unexpectedly, the best practices skill helps the assistant check for missing aliases.

In Codex and Claude Code, you can invoke skills directly via slash commands.

/pulumi-terraform-to-pulumi

Or describe what you need in natural language:

“Help me migrate this CDK application to Pulumi”

“Review this Pulumi code for best practices issues”

“Create a reusable component for a web service with load balancer”

The assistant will follow the skill’s procedures, ask clarifying questions when needed, and produce output that reflects Pulumi best practices rather than generic code generation.

Get started

We expect this collection to grow. If you have Pulumi expertise worth packaging, whether provider-specific patterns, debugging workflows, or operational practices, we welcome contributions. See the contributing guide for details.

The skills are available now in the agent-skills repository. Install them in your preferred AI coding environment and let us know what you build.