Skip to content

diegosouzapw/awesome-omni-skill / skills/ai-agents/agent-ops-constitution

agent-ops-constitution

Verified

Create/update .agent/constitution.md. Use when commands/boundaries/constraints must be confirmed before baseline or code changes. Draft v0 from repo evidence, then interview user.

Constitution workflow (mandatory before baseline)

Goal

Make .agent/constitution.md baseline-ready by confirming:

  • allowed/restricted/forbidden work areas
  • single-line build/lint/test/format commands
  • environment assumptions
  • project-specific constraints
  • issue-first workflow expectations

Pre-requisite: Context Map

Before starting constitution interview, ensure a context map exists:

  1. Check if .agent/map.md exists
  2. If NO map exists:
    πŸ“ No context map found. Creating one first to inform constitution questions...
    
    β†’ Invoke agent-ops-context-map to generate .agent/map.md
  3. If map exists but is stale (>30 days old or significant changes detected):
    πŸ“ Context map may be outdated. Refresh? [Y]es / [N]o
    
  4. Use the map to:
    • Pre-populate candidate work areas
    • Identify build/test tooling
    • Understand project structure for interview questions

Procedure

  1. Ensure context map exists (see above)
  2. Run tool detection β€” invoke agent-ops-tools or aoc tools scan --save
    • Creates .agent/tools.json with available development tools
    • Identifies missing recommended tools based on detected project type
    • Populates "Available tools" section in constitution
  3. Inspect repo evidence (README, CI workflows, package/build files). Do not guess.
  4. Draft v0 constitution:
    • every inferred item must cite its evidence ("CANDIDATE from ")
    • anything without evidence is TODO + UNCONFIRMED
    • use detected tools to suggest build/lint/test commands
  5. Interview the user:
    • one question per TODO/UNCONFIRMED item
    • ask both "what should it be?" and "why?"
  6. Update constitution until:
    • build + test commands are CONFIRMED
    • work boundaries are CONFIRMED
  7. Use agent-ops-state to update .agent/focus.md.
  8. Invoke agent-ops-tasks for any setup work discovered.

Issue Discovery During Constitution

After constitution setup, invoke agent-ops-tasks discovery:

  1. Collect setup items discovered:

    • Missing configuration β†’ CHORE issue
    • Broken scripts β†’ BUG issue
    • Missing documentation β†’ DOCS issue
    • Security concerns noted β†’ SEC issue
    • Environment issues β†’ CHORE issue
  2. Present to user:

    πŸ“‹ Constitution setup found {N} items to address:
    
    High:
    - [BUG] Build script references missing file
    - [CHORE] CI workflow needs updating
    
    Medium:
    - [DOCS] README is outdated
    
    Create issues for these? [A]ll / [S]elect / [N]one
    
  3. Workflow continues:

    • Issues created before baseline capture
    • Baseline can now proceed with known issues documented

Template

Start from constitution template.

Low Confidence Completeness Check (MANDATORY)

For LOW confidence work, constitution must be verified as complete before proceeding.

Required Sections Checklist

When confidence is LOW, verify constitution has ALL of these sections CONFIRMED (not TODO/UNCONFIRMED):

SectionRequiredPurpose
Project scopeβœ…What this project does
Work areas: allowedβœ…Where changes are permitted
Work areas: restrictedβœ…Where caution is required
Work areas: forbiddenβœ…Where changes are never allowed
Build commandβœ…Single-line build command
Test commandβœ…Single-line test command
Lint commandβœ…Single-line lint command
Format commandβšͺ OptionalSingle-line format command
Coverage commandβœ… for LOWHow to measure coverage
Environment assumptionsβœ…OS, runtime versions, dependencies
Tool detectionβœ….agent/tools.json exists
Constraintsβœ…Project-specific limitations
Default confidenceβœ…LOW/NORMAL/HIGH

Completeness Verification

Before LOW confidence work begins:

🎯 LOW CONFIDENCE CONSTITUTION CHECK

Checking constitution completeness for low confidence work...

| Section | Status |
|---------|--------|
| Project scope | βœ… CONFIRMED |
| Allowed areas | βœ… CONFIRMED |
| Restricted areas | βœ… CONFIRMED |
| Forbidden areas | ⚠️ TODO |
| Build command | βœ… CONFIRMED |
| Test command | βœ… CONFIRMED |
| Lint command | βœ… CONFIRMED |
| Coverage command | ❌ MISSING |
| Environment | βœ… CONFIRMED |
| Tool detection | βœ… .agent/tools.json exists |
| Constraints | ⚠️ UNCONFIRMED |

Result: INCOMPLETE β€” 3 items need confirmation

⚠️ Cannot proceed with low confidence work until constitution is complete.

Starting interview to fill gaps...

Staleness Check

For LOW confidence, also check constitution age:

AgeAction
< 7 daysProceed
7-30 daysPrompt: "Constitution is {N} days old. Review before proceeding?"
> 30 daysRequire: "Constitution is stale. Re-interview before low confidence work."

Gap-Filling Interview

If constitution is incomplete for LOW confidence:

  1. List missing/unconfirmed sections
  2. Invoke agent-ops-interview for each gap
  3. Update constitution with confirmed values
  4. Re-verify completeness
  5. Only proceed when all required sections are CONFIRMED
πŸ“‹ Constitution gaps for low confidence work:

1. Forbidden work areas (currently: TODO)
2. Coverage command (currently: MISSING)
3. Constraints (currently: UNCONFIRMED)

Starting interview to fill these gaps...

Q1: What areas of the codebase should NEVER be modified?
(These will be marked as forbidden work areas)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why β€” repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" β€” or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself β€” your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall