Co-developing AIAgentMinder with Claude (Part 1 — Opus 4.6 Review)

For a few weeks I’ve been working on a tool, AIAgentMinder, to help me use Claude Code more effectively. Naturally I figured I should use Claude to improve the tool I’m using to improve Claude. Only makes sense.

First, what it is — my repo blurb: A governance and lifecycle control framework for Claude Code. Adds persistent auditable memory, ADR tracking, risk-aware testing, and structured planning to transform Claude from helpful assistant into a production-ready project engine. Deploy AI-assisted projects that stay organized, maintainable, and accountable across sessions.

Mostly, I’ve been quite pleased.

Project creation works really well. New project — check. Bring in mid-development on something else? Also check. /setup works like a charm.

Resuming work is easy. I say “resume”

But there are some nagging concerns — Permissions aren’t quite working as I expected. And I don’t really know: how efficient is it really? Then there’s Opus 4.6 out now, and a new MCP server hourly. Is my tooling up to date? Is it already obsolete?

The only reasonable thing to do at this point is ask Claude Opus 4.6 for a Review of the project. In part 2 I’ll post the results of implementing its suggestions.

My prompt to Claude Opus 4.6:

Context/Environment: Latest desktop Claude app on Windows, opus 4.6, pretty liberal MCP and web access. Access to the local repo, which is also here: https://github.com/lwalden/AIAgentMinder

Prompt: “I’d like an analysis of this repo — start by reading the directory tree and summarize the structure before diving into content review. The purpose of the repo is spelled out in the readme.md file. Claude and VS Code along with the MCP server environment and GitHub are all changing rapidly. Given the goals of this repo — in most abstract terms to help the user bring ideas — general to specific about a new software project through the planning and develop stages to MVP and production and beyond, if the user wishes to go that far — all efficiently in terms of AI token use, and with a quality end product in mind. I’m open to removing features that are no longer useful, modifying features to be better at what they are trying to do now, and adding features that lead to completion of the goals. Also open to hard feedback, for instance if the tooling is not useful, that should be explained.”

And here was Opus 4.6’s feedback:

I’ve now read every file in the repo. Let me compose the analysis.

#Repository Structure Summary

aiagentminder/
├── .claude/
│   ├── commands/setup.md          ← Root-level /setup (runs FROM the template repo)
│   └── settings.local.json        ← Local dev permissions (your personal TradingSystem leftovers)
├── docs/
│   ├── customization-guide.md     ← How to customize the template
│   ├── how-it-works.md            ← Explains the 4-file context system
│   └── strategy-creation-guide.md ← Guide for /plan and manual roadmap creation
├── project/                       ← THE TEMPLATE (copied to target projects)
│   ├── .claude/
│   │   ├── commands/
│   │   │   ├── archive.md         ← /archive slash command
│   │   │   ├── checkpoint.md      ← /checkpoint slash command
│   │   │   ├── plan.md            ← /plan slash command
│   │   │   ├── setup.md           ← /setup (runs FROM the target project)
│   │   │   └── status.md          ← /status slash command
│   │   └── settings.json          ← Pre-approved permissions (132 allow entries)
│   ├── .github/
│   │   ├── workflows/ci.yml       ← CI skeleton
│   │   ├── workflows/deploy.yml   ← Deploy skeleton
│   │   └── dependabot.yml         ← Dependabot config
│   ├── docs/
│   │   ├── ARCHITECTURE.md        ← Architecture template
│   │   └── strategy-roadmap.md    ← Strategy/roadmap template
│   ├── .env.example
│   ├── .gitignore                 ← 239-line mega-gitignore
│   ├── CLAUDE.md                  ← Main project instructions (105 lines)
│   ├── DECISIONS.md               ← ADR template
│   └── PROGRESS.md                ← Session continuity tracker
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── README.md

Two layers: The root is the “meta-repo” (docs, changelog, the root /setup command). The project/ directory is the actual template that gets copied into target projects.

#Analysis: What Works, What Doesn’t, and What’s Missing

#What’s genuinely valuable

1. The 4-file context system (CLAUDE.md, PROGRESS.md, DECISIONS.md, strategy-roadmap.md) This is the core intellectual contribution and it’s sound. The idea that Claude should have a small, always-read instruction file, a session continuity file, a decision log, and an on-demand strategy doc maps well to how Claude Code actually works. The context budget table and file-reading strategy are smart — they show awareness that every token read per session has a compounding cost.

2. The /plan command This is the strongest single feature. The 4-tiered starting point assessment (rough concept → detailed spec) is well-designed. The grouped question rounds prevent the classic Claude problem of asking one question at a time. The quality tier system (Lightweight → Comprehensive) is practical. This command genuinely adds value over Claude’s native plan mode.

3. The /checkpoint and /archive lifecycle commands These solve a real problem: session continuity across conversations. Claude Code’s built-in MEMORY.md is automatic but opaque. Having an explicit, git-tracked PROGRESS.md that humans can audit and edit is better for production projects. The archive mechanism prevents unbounded growth.

4. The root-level /setup separation The fix on this branch (two setup commands — one in the template repo, one in the target project) correctly solves the chicken-and-egg problem. This was a good architectural call.

#Hard feedback: What should change or be removed

1. The permissions file (settings.json) is counterproductive — REMOVE or drastically reduce

This is the biggest problem in the repo. The 132-line allow list pre-approves curl:*, wget:*, openssl:*, all cloud CLIs (az:*, aws:*, gcloud:*, terraform:*), all container tools (docker:*, kubectl:*, helm:*), system package managers (apt:*, brew:*, choco:*), and shells (powershell.exe:*, cmd.exe:*, wsl:*).

Problems:

• Security theater. The deny list only blocks rm -rf /, rm -rf ~, rm -rf C:, and force-push. But curl can exfiltrate data. docker can mount the host filesystem. terraform can create cloud resources (only destroy is dangerous?). kubectl can deploy anything. aws/az/gcloud can provision billable resources. This gives a false sense of safety.
• It undermines Claude Code’s own safety model. Claude Code asks for permission deliberately. The prompt-based approval is a feature, not a bug. Users learn what Claude is doing by approving commands. Blanket pre-approval trains users to stop paying attention.
• The /setup “trim” step is a fiction. The command says to remove unused stack permissions, but in practice Claude will copy the whole file and might trim a few lines. The user won’t audit 132 entries.
• Recommendation: Strip this to git, gh, and the specific stack tools for the project. Maybe 15–20 entries. Let users add more as needed. Remove all cloud CLIs, system package managers, shells, and network tools. The “setup trims it” approach doesn’t work — start minimal.

2. The CI/CD scaffolding is premature — REMOVE

The ci.yml, deploy.yml, and dependabot.yml are skeletons with placeholder comments. They add cognitive overhead without providing value:

• CI has a path-filter change detection job but no actual build job. It will run, do nothing useful, and show as “passed” — misleading.
• The deploy workflow has a literal echo "Configure deployment steps" placeholder.
• These files will be generated more accurately by Claude when the user actually needs them, with full context of their real project structure.
• Recommendation: Remove all three. Add a note in the /plan or /setup command: “When you’re ready for CI/CD, ask Claude to set it up.” Claude Code is excellent at generating GitHub Actions workflows from scratch when it can see the actual project.

3. The .env.example adds little value — REMOVE

It contains APP_NAME=my-project and generic comments. Any developer knows about .env files. Claude will generate the right one when the project needs it. This is template clutter.

4. The mega-gitignore is 239 lines of everything — TRIM

It covers Python, .NET, Rust, Java, Ruby, Go, Terraform, Docker, Gatsby, Nuxt, VuePress, Storybook, Turborepo… This is a kitchen-sink .gitignore for every language. GitHub’s gitignore repo exists for this. The /setup command should generate a project-appropriate one (or just use gh repo create which offers gitignore templates).

Recommendation: Reduce to a small core (IDE, OS, secrets, .env) and let /setup append stack-specific entries, or just point to GitHub’s templates.

5. The project/ setup command is a duplicate — REMOVE

project/.claude/commands/setup.md is meant to be copied into target projects. But once a project is set up, why would you run /setup again? It’s 167 lines of dead weight in every project that uses this template. The root-level setup is the one that matters.

Recommendation: Remove project/.claude/commands/setup.md. If someone needs to re-run setup, they do it from the template repo.

6. ARCHITECTURE.md template is too generic to help

It’s 28 lines of [Component], [What it does], [Where it is] placeholders. Claude can generate a better architecture doc from scratch by reading the actual codebase. This file will either stay as placeholders forever or be completely rewritten.

Recommendation: Remove from the template. Add it as a step in /plan or /checkpoint when the project reaches a certain maturity.

7. DECISIONS.md starts empty and the format is over-specified

The template prescribes ADR-NNN and PDR-NNN numbering schemes. In practice, developers on solo/small projects won’t maintain sequential numbered ADRs. The real value is just having a file where Claude logs decisions so it doesn’t re-debate them.

Recommendation: Simplify to a flat list format. Let structure emerge organically.

#What’s missing

1. No hooks integration

Claude Code supports hooks — shell commands that run automatically on events like PreToolCall, PostToolCall, Notification, etc. This is a perfect fit for AIAgentMinder’s goals:

• A PostToolCall hook on Write or Edit could auto-update PROGRESS.md
• A Notification hook could checkpoint before session end
• A hook could enforce “read PROGRESS.md first” at session start

This would make the governance automatic rather than relying on Claude reading and following CLAUDE.md instructions.

2. No MCP server awareness

MCP servers are now a core part of Claude Code’s ecosystem. The template doesn’t mention them at all. For projects that use MCP servers (databases, APIs, custom tools), the /setup and /plan commands should ask about and configure MCP.

3. No guidance for Claude Code’s native features that overlap

Claude Code now has:

• Built-in /init that generates CLAUDE.md
• Auto memory via MEMORY.md
• Plan mode (native)
• Compact history (automatic context management)

The README comparison table is good but needs updating. More importantly, the template should work with these features, not pretend they don’t exist. For example, CLAUDE.md should explicitly say “Do NOT use MEMORY.md for this project; use PROGRESS.md instead” if that’s the intent.

4. No multi-agent / sub-agent awareness

Claude Code’s Task tool can spawn sub-agents. For larger projects, the strategy roadmap could identify which phases or tasks are parallelizable and suggest when to use sub-agents vs. sequential work.

5. No cost/token awareness tooling

You mentioned token efficiency as a core goal, but there’s no mechanism to measure or optimize it. Even a simple “at session end, note approximately how many tokens this session used” in /checkpoint would help users understand their burn rate.

6. The “Next Steps” after setup is a dead end

After /setup + /plan, the README says: Tell Claude: "Read CLAUDE.md and docs/strategy-roadmap.md, then start Phase 1." This is the weakest part of the experience. There should be a /start or /build command that actually kicks off Phase 1 with proper context loading, or the session protocol in CLAUDE.md should be robust enough that just opening Claude Code and saying “let’s go” works.

#Summary Scorecard

The core concept — giving Claude Code structured project memory and a planning workflow — is sound and fills a real gap. The main problems are scope creep (trying to be a full DevOps scaffolder) and the permissions file working against Claude Code’s safety model. Lean it down to what only AIAgentMinder can do: project memory, structured planning, and session lifecycle management. Let Claude Code handle the rest natively.

Back to me writing: So it turns out permissions were a big issue, just not quite the way I’d thought. In the end, I can’t argue with its take too much. Frankly, I’m excited to see how it implements its feedback — especially hook integration. I’ll post a part 2 when it’s done.