> ## Documentation Index
>
> Fetch the complete documentation index at: https://superpowers.frontis.nl/llms.txt
> Use this file to discover all available pages before exploring further.

---

title: Superpowers workflow
summary: How Frontis uses Superpowers as the required workflow layer for non-trivial coding-agent work across .NET, Nuxt and Azure DevOps repositories.
order: 30

---

# Superpowers workflow

Use this guide when working with Superpowers in Frontis repositories.

Superpowers is the workflow layer for serious coding-agent work. It helps agents avoid jumping straight into implementation and instead follow a disciplined flow:

```text
clarify -> spec -> plan -> implement with tests -> review -> verify -> finish
```

For Frontis, Superpowers should be used together with:

```text
AGENTS.md
.frontis/project.json
.frontis/project-context.yaml
.frontis/naming-convention.yaml
.frontis/azure-conventions.yaml
.github/copilot-instructions.md
.github/instructions/*.instructions.md
```

Local repository files remain the source of truth for project identity, naming, Azure resources and pipeline conventions.

## What Superpowers is

Superpowers is an agentic software-development methodology built from composable skills.

It is not a replacement for:

- local Frontis conventions;
- code review;
- CI validation;
- Azure DevOps branch policies;
- secure deployment controls;
- developer judgement.

It is a process layer that teaches coding agents to work in a more structured way.

Superpowers is especially useful when an agent must:

- clarify an unclear task;
- design a feature;
- write an implementation plan;
- use TDD;
- debug systematically;
- work in a branch or worktree;
- request or respond to review;
- finish a development branch safely.

## When Superpowers is required

Use Superpowers for non-trivial work.

Required for:

- new features;
- bug fixes with unknown root cause;
- refactors;
- .NET API behavior changes;
- Nuxt feature work;
- Azure DevOps YAML pipeline changes;
- Azure infrastructure changes;
- authentication or authorization changes;
- data migrations;
- performance-sensitive changes;
- security-sensitive changes;
- changes touching multiple projects or layers;
- any task where the agent may edit many files.

Recommended for:

- creating new repositories;
- introducing new conventions;
- writing or changing test strategy;
- debugging flaky tests;
- debugging failing Azure Pipelines;
- preparing pull requests.

Not required for:

- typo fixes;
- small copy changes;
- formatting-only changes;
- reading code without changing it;
- answering simple questions;
- tiny one-file changes with no behavioral impact.

Even for small changes, the agent must still follow local repository instructions.

## Source-of-truth priority

When using Superpowers in a Frontis repository, use this priority order:

1. explicit user instruction;
2. local repository files;
3. Frontis online agent documentation;
4. Superpowers workflow;
5. general model knowledge.

Local files override generic examples.

Before designing or editing, read:

```text
AGENTS.md
.frontis/project.json
.frontis/project-context.yaml
.frontis/naming-convention.yaml
.frontis/azure-conventions.yaml
```

Read `azure-conventions.yaml` whenever the task involves:

- Azure resources;
- hosting;
- environments;
- App Services;
- Storage;
- SQL;
- Application Insights;
- Log Analytics;
- Key Vault;
- deployment;
- Azure DevOps pipelines.

## Frontis startup procedure

At the start of a Superpowers session, the agent should do this:

1. Read `AGENTS.md`.
2. Read `.frontis/project.json`.
3. Read `.frontis/project-context.yaml`.
4. Read `.frontis/naming-convention.yaml`.
5. Read `.frontis/azure-conventions.yaml` if Azure, pipelines, hosting or deployment are involved.
6. Read `https://docs.frontis.nl/ai/llms.txt` when web access is available.
7. Identify which Superpowers workflow applies.
8. Summarize the effective project context.
9. Ask only necessary clarifying questions.
10. Produce a short spec before implementation.

The effective project context summary should include:

```text
company
product
component
canonical project name
hosting model
environments
team
GRIPP number
relevant naming rules
relevant pipeline naming rules
relevant Azure hosting rules
```

## Required Superpowers flow

For non-trivial Frontis work, use this flow.

### 1. Clarify

Do not start coding immediately.

Clarify:

- what the user wants;
- what problem should be solved;
- what is in scope;
- what is out of scope;
- affected systems;
- expected behavior;
- acceptance criteria;
- risks.

Ask questions only when needed.

If the task is clear enough, state assumptions and proceed to a short spec.

### 2. Spec

Write a short design/spec.

The spec should include:

- goal;
- non-goals;
- affected files or areas;
- user-visible behavior;
- API behavior where applicable;
- test strategy;
- risks;
- rollback or recovery concerns when relevant.

Keep the spec concise.

Do not hide risky assumptions.

### 3. Plan

Write an implementation plan before editing.

The plan should contain small steps.

Each step should include:

- exact files likely to change;
- implementation intent;
- tests or validation;
- expected result.

For Frontis repositories, the plan must mention whether the task touches:

- .NET;
- Nuxt;
- Azure DevOps YAML;
- Azure resources;
- naming conventions;
- repository bootstrap files;
- CI validation.

### 4. Branch or worktree

For larger changes, use a dedicated branch or worktree.

Recommended branch naming:

```text
feature/<short-description>
bugfix/<short-description>
chore/<short-description>
```

Follow local repository conventions when present.

Before starting implementation:

- check git status;
- avoid mixing unrelated changes;
- preserve user changes;
- do not overwrite uncommitted work.

### 5. TDD for behavior changes

For behavior changes, use TDD.

Follow:

```text
red -> green -> refactor
```

Expected behavior:

1. write or update a test first;
2. run the test and confirm it fails for the expected reason;
3. write minimal implementation;
4. run the test and confirm it passes;
5. refactor only after the test passes;
6. run relevant broader tests.

Do not claim TDD was used unless the failing test was observed.

If a repository has no test setup, state that and propose the smallest useful validation.

### 6. Implement

Implement according to the approved plan.

Rules:

- keep changes small;
- avoid unrelated cleanup;
- avoid broad rewrites;
- preserve existing style;
- follow local `.frontis` conventions;
- do not invent names;
- do not add secrets;
- do not change production deployment behavior without approval.

### 7. Review

Before declaring completion, review the change.

Review for:

- spec compliance;
- code quality;
- test coverage;
- naming consistency;
- Azure convention consistency;
- pipeline validity;
- security risks;
- unnecessary complexity;
- scope creep.

Critical issues block completion.

### 8. Verify

Run relevant validation.

Typical .NET validation:

```bash
dotnet restore
dotnet build
dotnet test
```

Typical Nuxt validation:

```bash
npm install
npm run lint
npm run typecheck
npm run test
npm run build
```

Typical docs validation:

```bash
node scripts/generate-llms.mjs --source docs/ai --out wwwroot
```

Typical Azure DevOps validation:

```bash
az pipelines validate
```

Only run commands that apply to the repository.

If commands cannot be run, state exactly what was not run and why.

Never say "tests pass" unless tests were actually run and passed.

### 9. Finish

At the end, provide a concise completion summary:

```text
changed
verified
not verified
risks
next steps
```

For larger branches, suggest:

- create PR;
- request review;
- run Azure DevOps pipeline;
- merge after checks pass;
- discard branch if experiment failed.

## Frontis-specific rules

### Naming

Agents must not invent:

- project names;
- namespaces;
- solution names;
- test project names;
- Azure resource names;
- pipeline filenames;
- directory names.

Read local convention files first.

When a name must be derived, show the derived value before using it if the change is non-trivial.

### Azure DevOps pipelines

When editing Azure DevOps YAML:

1. read `.frontis/project.json`;
2. read `.frontis/naming-convention.yaml`;
3. read `.frontis/azure-conventions.yaml`;
4. follow the repository pipeline naming convention;
5. keep build, validation, artifact and deploy stages clear;
6. never put secrets in YAML;
7. use service connections, variable groups or secure variables;
8. note that Azure Repos PR validation is normally configured through branch policies.

Do not change deployment targets without explicit approval.

### .NET

When changing .NET code:

- follow the target framework already used by the project;
- use the current Frontis default only when creating new projects;
- keep namespaces aligned with the canonical project identity;
- write tests for behavior changes;
- do not introduce vague projects such as `Common`, `Helpers`, `Utilities`, `Misc`, `Shared` or `General` unless explicitly allowed.

### Nuxt

When changing Nuxt code:

- follow existing structure;
- prefer typed contracts;
- keep composables focused;
- avoid global state unless justified;
- align frontend API contracts with backend behavior;
- add or update tests where a test setup exists.

## Human approval boundaries

Agents must stop and ask before:

- deleting files;
- performing destructive commands;
- changing production deployment behavior;
- changing Azure resource names;
- changing authentication or authorization behavior;
- changing database schema or data migration logic;
- editing secrets or secret references;
- overwriting existing convention files;
- making large cross-cutting refactors;
- changing branch policies or security settings;
- executing unknown remote scripts.

Approval request should include:

```text
what will change
why it is needed
risk
rollback
exact command or files involved
```

## Caveman integration

Caveman may be used with Superpowers to reduce output tokens.

Default Frontis policy:

```text
Superpowers = workflow discipline
Frontis .frontis files = source of truth
Caveman lite = concise progress updates
CI validation = hard gate
```

Use Caveman lite for:

- progress updates;
- short summaries;
- repeated agent-loop status.

Do not use Caveman style for:

- security warnings;
- production deployment instructions;
- destructive actions;
- database migrations;
- secrets;
- PR descriptions;
- commit messages;
- client-facing documentation;
- any instruction where exact sequencing matters.

When clarity conflicts with compression, clarity wins.

## Recommended prompts

### Start a non-trivial task

```text
Use Superpowers workflow.

Read AGENTS.md.
Read .frontis/project.json.
Read .frontis/project-context.yaml.
Read .frontis/naming-convention.yaml.
Read .frontis/azure-conventions.yaml if Azure, pipelines, hosting or deployment are involved.
Read https://docs.frontis.nl/ai/llms.txt when web access is available.

Summarize the effective project context.
Then create a short spec, implementation plan and validation plan.
Do not edit files until the plan is clear.
Use Caveman lite for progress updates.
```

### Start a bug investigation

```text
Use Superpowers systematic debugging.

Read AGENTS.md and .frontis/*.yaml.
Do not guess.

First:
1. describe the symptom;
2. identify the expected behavior;
3. gather evidence;
4. propose likely causes;
5. choose the smallest verification step.

Do not implement a fix until the root cause is supported by evidence.
```

### Start a pipeline change

```text
Use Superpowers workflow for this Azure DevOps pipeline change.

Read:
- AGENTS.md
- .frontis/project.json
- .frontis/naming-convention.yaml
- .frontis/azure-conventions.yaml
- existing pipeline YAML files

Summarize the current pipeline structure.
Then propose the smallest safe change and validation plan.
Do not add secrets to YAML.
Do not change production deployment behavior without approval.
```

### Start a feature

```text
Use Superpowers workflow and TDD.

Read AGENTS.md and .frontis/*.yaml.
Clarify acceptance criteria.
Write a short spec.
Write an implementation plan.
Write or update tests before implementation.
Verify with relevant build, test and lint commands.
```

### Finish a task

```text
Finish this Superpowers task.

Review the changes against the spec and plan.
Run relevant validation if possible.
Summarize:
- changed files;
- tests run;
- validation results;
- risks;
- follow-up actions;
- whether the branch is ready for PR.
```

## Recommended installation guidance

Install Superpowers per agent harness.

Always check the official Superpowers repository for the current installation method:

```text
https://github.com/obra/superpowers
```

Typical harnesses include:

- Claude Code;
- Codex CLI;
- Codex App;
- Factory Droid;
- Gemini CLI;
- OpenCode;
- Cursor;
- GitHub Copilot CLI.

Do not assume that installing Superpowers in one harness installs it in another.

## Frontis rollout policy

For Frontis teams, use this adoption model:

```text
small change:
  normal IDE assistant is fine

medium change:
  short spec + plan + tests

large change:
  Superpowers workflow required

pipeline or Azure infrastructure change:
  Superpowers workflow required

security or production change:
  Superpowers workflow + explicit human approval required
```

For a team of multiple developers, prefer standard repository files over personal prompt habits.

Keep these files committed:

```text
AGENTS.md
.github/copilot-instructions.md
.github/instructions/*.instructions.md
.github/prompts/*.prompt.md
.frontis/*.yaml
.frontis/project.json
```

## Pull request checklist

Before opening a PR, verify:

```text
[ ] AGENTS.md and .frontis files were followed
[ ] task had clear scope
[ ] spec or plan exists for non-trivial work
[ ] tests were added or updated for behavior changes
[ ] relevant validation commands were run
[ ] Azure pipeline changes avoid secrets
[ ] names follow local conventions
[ ] no unrelated refactors included
[ ] no user changes overwritten
[ ] remaining risks documented
```

## Anti-patterns

Avoid:

- coding before understanding the task;
- skipping the spec for complex work;
- writing implementation before tests for behavior changes;
- making broad unrelated cleanups;
- changing generated files manually without understanding the generator;
- inventing Frontis conventions;
- using outdated online docs over local repository files;
- claiming success without verification;
- compressing important warnings with Caveman;
- letting an agent run for a long time without review checkpoints.

## Completion summary format

Use this format at the end of a Superpowers task:

```text
Summary
- ...

Changed
- ...

Verified
- ...

Not verified
- ...

Risks
- ...

Next steps
- ...
```

Keep it concise, but do not omit important caveats.