My Superpowers + AgentOps Workflow
This is my reference workflow for using AI as more than a chat prompt.
The goal is simple:
Use AI to help maintain real projects without losing context, skipping validation, or turning the repo into a mess.
This workflow works for PowerShell, Go, Python, JavaScript, websites, infrastructure code, or almost any software project.
The Short Version
I use two things together:
Superpowers = the agent’s engineering workflow
AgentOps = the repo’s memory and audit trail
Superpowers helps the AI work like a careful developer.
AgentOps makes sure the project remembers what happened.
Together, they turn this:
Prompt → Code → Hope
into this:
Context → Plan → Change → Validate → Document → Review
Why This Is More Than Chat Prompting
Normal AI chat is usually one-shot:
Ask question
Get answer
Copy code
Hope it works
That is useful, but limited.
With Superpowers + AgentOps, the AI can do more advanced agentic work:
Read the repo
Understand existing files
Use project-specific instructions
Create a plan
Edit files
Run commands
Run tests
Inspect failures
Fix issues
Record decisions
Update documentation
Repeat the loop
That is the big difference.
The AI is no longer only answering questions. It is operating inside the project with tools, memory, validation, and guardrails.
The Mental Model
Think of the workflow like this:
Superpowers
Helps the agent plan, debug, test, review, and refactor.
AgentOps
Stores project context, decisions, validation results, audit notes, and lessons learned.
Git
Protects the project with branches, diffs, and rollback.
Tests / Build / Lint
Prove whether the work actually succeeded.
The agent should never just say:
Done.
It should say:
Here is what changed.
Here is why it changed.
Here are the commands I ran.
Here is what passed.
Here is what still needs work.
Installation
1. Install Claude Code
On Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
Alternative with WinGet:
winget install Anthropic.ClaudeCode
Verify:
claude --version
Open a repo:
cd C:\Path\To\YourRepo
claude
2. Install Superpowers
Inside Claude Code:
/plugin install superpowers@claude-plugins-official
Restart Claude Code after installing.
3. Install AgentOps
From your terminal:
claude plugin marketplace add boshu2/agentops
claude plugin install agentops@agentops-marketplace
Restart Claude Code, then run:
/quickstart
4. Optional: Install the AgentOps CLI
On Windows PowerShell:
irm https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-ao.ps1 | iex
ao version
The CLI is optional, but useful for repo bookkeeping and health checks.
Recommended Repo Files
I like every serious repo to have an .agents folder:
.agents/
├── context.md
├── decisions.md
├── validation.md
├── audit.md
├── refactor-plan.md
└── lessons-learned.md
These files are not magic. They are plain Markdown files.
That is the point.
They make the project self-documenting.
What Each File Does
.agents/context.md
What this repo is, how it works, and what future AI sessions need to know.
.agents/decisions.md
Important decisions and why they were made.
.agents/validation.md
Commands that were run and whether they passed or failed.
.agents/audit.md
Risks, gaps, missing tests, security concerns, and technical debt.
.agents/refactor-plan.md
The plan for improving the project.
.agents/lessons-learned.md
Reusable knowledge discovered while working on the repo.
First Run on an Existing Repo
The first run should be mostly read-only.
Do not start by asking the AI to rewrite everything.
Use this prompt:
Use Superpowers and AgentOps.
This is an existing project that needs review and cleanup.
Goal:
Perform a one-time bootstrap and audit pass.
Rules:
- Do not rewrite the project.
- Do not make broad refactors.
- Do not change behavior unless required to fix a broken validation step.
- Prefer read-only inspection.
- If fixes are needed, create a prioritized plan first.
- Ask before applying anything risky.
- Do not commit anything.
Tasks:
1. Detect the project type, language, framework, package manager, runtime, and structure.
2. Create or update AgentOps files under .agents/.
3. Inspect README, configuration, scripts, source code, tests, environment examples, and deployment files.
4. Identify available validation commands such as lint, test, typecheck, build, or equivalent.
5. Run only safe existing validation commands.
6. Record exact commands and results in .agents/validation.md.
7. Record repo overview in .agents/context.md.
8. Record assumptions and decisions in .agents/decisions.md.
9. Record risks, missing tests, security concerns, documentation gaps, and maintenance issues in .agents/audit.md.
10. Record reusable lessons in .agents/lessons-learned.md.
11. Create a prioritized checklist:
- Critical
- Important
- Nice-to-have
Stop after producing the audit report.
Maintenance Prompt
For normal day-to-day work:
Use Superpowers and AgentOps.
Task:
<describe the change>
Before editing:
1. Read .agents/context.md.
2. Read .agents/decisions.md.
3. Check git status.
4. Make a short plan.
Rules:
- Keep the change small.
- Preserve existing behavior unless the task requires changing it.
- Update or add tests where appropriate.
- Run the relevant validation commands.
- Record commands and results in .agents/validation.md.
- Record important decisions in .agents/decisions.md.
- Record reusable lessons in .agents/lessons-learned.md.
- Do not commit unless I explicitly ask.
End with:
1. Summary of changes
2. Files changed
3. Validation results
4. Remaining risks
Refactor / Overhaul Prompt
For a bigger cleanup:
Use Superpowers and AgentOps.
This project needs a significant overhaul.
Goal:
Modernize the project while preserving behavior where possible.
Rules:
- Do not rewrite everything in one pass.
- Work in small phases.
- Preserve current behavior unless a change is explicitly justified.
- Do not remove code you do not understand.
- Do not invent requirements.
- Do not commit anything.
- Record everything important in AgentOps files.
Phase 1: Discovery
- Inspect the repo.
- Identify entry points, dependencies, configuration, tests, build process, and external systems.
- Identify risks, bugs, missing tests, and documentation gaps.
- Update .agents/context.md and .agents/audit.md.
- Do not modify code.
Phase 2: Validation baseline
- Detect available validation commands.
- Run safe validation commands.
- Record exact results in .agents/validation.md.
Phase 3: Refactor plan
- Create .agents/refactor-plan.md.
- Describe the current architecture.
- Describe the target architecture.
- Break the work into small phases.
- Identify risks and rollback strategy.
- Stop for approval.
Phase 4: Implementation
- Implement one phase at a time.
- Add or update tests where appropriate.
- Run validation.
- Update AgentOps files.
- Stop for review after each phase.
Start with Phase 1 only.
Permission Modes
I normally use permission modes like this:
Plan / audit:
plan mode
Normal code edits:
acceptEdits mode
Long trusted tasks:
auto mode
Disposable sandbox or VM only:
bypassPermissions
Example:
claude --permission-mode plan
For editing:
claude --permission-mode acceptEdits
For higher autonomy:
claude --permission-mode auto
I avoid this unless I am in a throwaway repo, sandbox, or VM:
claude --dangerously-skip-permissions
My Standard Workflow
Before any major AI-assisted change:
1. Create a branch
2. Start Claude Code
3. Use Superpowers + AgentOps
4. Run audit or plan first
5. Let the agent make small changes
6. Run validation
7. Review the diff
8. Commit manually
Example:
git status
git checkout -b agentops-maintenance
claude --permission-mode acceptEdits
After the agent finishes:
git diff
git status
Then I decide whether to commit.
The Main Rule
The AI should not just produce code.
It should produce evidence.
Good output looks like this:
Changed:
- These files
Validated:
- These commands ran
- These passed
- These failed
Documented:
- These decisions were recorded
- These risks remain
Next:
- Recommended follow-up tasks
That is why I use Superpowers and AgentOps together.
Superpowers gives the agent a better development process.
AgentOps makes the work self-documenting.
Together, they turn AI from a chat assistant into a repeatable engineering workflow.