| name | brownfield-constitution |
| description | This skill MUST be invoked when the user says "create constitution for existing codebase", "codify existing patterns", "brownfield constitution", "essential floor", or "emergent ceiling". SHOULD also invoke when user mentions "brownfield", "evolution roadmap", or "legacy project". Extends authoring-constitution. |
Brownfield Constitution Authoring
Overview
Write project constitutions for existing codebases using the Essential Floor + Emergent Ceiling approach. This skill extends humaninloop:authoring-constitution with brownfield-specific guidance that respects existing patterns while establishing governance.
The core insight: existing codebases have implicit conventions worth preserving (Emergent Ceiling) but may lack foundational governance in critical areas (Essential Floor). This skill helps codify both.
When to Use
Applicable when:
- Creating a constitution for an existing codebase (brownfield project)
- The codebase has existing patterns, conventions, or architecture worth preserving
- You need to establish governance without disrupting working code
- The user mentions "brownfield", "existing codebase", or "legacy project"
- Codifying implicit conventions into explicit, enforceable principles
When NOT to Use
- New project from scratch: REQUIRED alternative - Use
humaninloop:authoring-constitution directly
- Codebase analysis not completed: REQUIRED prerequisite - Run
humaninloop:analysis-codebase first
- Project too small for formal governance: Single-file scripts, prototypes do not need constitutions
- Validating existing constitution: OPTIONAL - Use
humaninloop:validation-constitution
Prerequisites
REQUIRED: This skill extends humaninloop:authoring-constitution. Prerequisites for brownfield mode:
- Understand core principles: Read
humaninloop:authoring-constitution for the Three-Part Principle Rule (Enforcement, Testability, Rationale)
- Know RFC 2119 keywords: See RFC-2119-KEYWORDS.md in
humaninloop:authoring-constitution
- Understand SYNC IMPACT format: See SYNC-IMPACT-FORMAT.md in
humaninloop:authoring-constitution
- Run codebase analysis: Execute
humaninloop:analysis-codebase to understand existing patterns
Brownfield constitutions follow all rules from humaninloop:authoring-constitution, plus additional guidance for existing codebases.
- Essential Floor: Four NON-NEGOTIABLE categories every constitution MUST address
- Emergent Ceiling: Good patterns from the codebase worth codifying
Essential Floor (NON-NEGOTIABLE)
Every constitution MUST include principles for these four categories, regardless of codebase state:
| Category | Minimum Requirements | Default Enforcement |
|---|
| Security | Auth at boundaries, secrets via env/secret managers, input validation, secret scanning in CI | Integration tests, code review, secret scanning tools |
| Testing | Automated tests exist, coverage ≥80% (configurable), ratchet rule (coverage MUST NOT decrease) | CI test gate, coverage threshold with warning/blocking levels |
| Error Handling | Explicit handling, RFC 7807 Problem Details format, correlation IDs in responses | Schema validation in tests, code review |
| Observability | Structured logging, correlation IDs, APM integration, no PII in logs | Config verification, log audit, APM dashboards |
See references/ESSENTIAL-FLOOR.md for detailed requirements and example principles for each category.
Writing Essential Floor Principles:
- If codebase has the capability → Principle codifies existing pattern with enforcement
- If codebase lacks the capability → Principle states "MUST implement" with roadmap gap
Emergent Ceiling (FROM CODEBASE)
Beyond the essential floor, identify existing good patterns worth codifying:
- Read codebase analysis - Look for "Strengths to Preserve" section
- Identify patterns - Naming conventions, architecture patterns, error formats
- Codify as principles - With enforcement mechanisms
See references/EMERGENT-CEILING-PATTERNS.md for the pattern library with examples.
Common Pattern Categories:
| Pattern Category | What to Look For |
|---|
| Code Quality | Documentation requirements, API annotations, deprecation handling |
| Architecture | Layer rules, dependency injection, module boundaries |
| API Design | Response formats, versioning, pagination |
| Authorization | Role-based access, permission checks |
| Resilience | Retry policies, circuit breakers, timeouts |
| Configuration | Strongly-typed options, feature flags |
| Error Handling | Error display guidelines, data resilience |
| Observability | Log levels, context requirements, crash reporting |
| Product Analytics | Event categories, naming conventions, funnel tracking |
| Naming Conventions | File/class/variable naming, directory structure |
Brownfield Constitution Structure
# [Project] Constitution
<!-- SYNC IMPACT REPORT -->
## Core Principles
### Essential Floor Principles
I. Security by Default
II. Testing Discipline
III. Error Handling Standards
IV. Observability Requirements
### Emergent Ceiling Principles
V. [Pattern from codebase]
VI. [Pattern from codebase]
...
## Technology Stack
[From codebase analysis]
## Quality Gates
[From codebase analysis + essential floor requirements]
## Governance
[Standard governance section]
## Evolution Notes
This constitution was created from brownfield analysis.
**Essential Floor Status** (from codebase-analysis.md):
| Category | Status | Gap |
|----------|--------|-----|
| Security | partial | GAP-001 |
| Testing | partial | GAP-002 |
| Error Handling | present | - |
| Observability | absent | GAP-003 |
See `.humaninloop/memory/evolution-roadmap.md` for improvement plan.
Brownfield Quality Checklist
Additional checks for brownfield constitutions (beyond standard checklist):
After completing brownfield constitution, run validation using humaninloop:validation-constitution.
Common Mistakes
Mistake 1: Skipping Essential Floor Categories
Problem: Assuming the codebase "doesn't need" security or observability principles because it "seems simple" or "works fine."
Why it's wrong: Essential floor categories exist because these are areas where missing governance causes the most damage. A working codebase without security principles will eventually have a security incident.
Fix: Always include all four essential floor categories. If the codebase lacks capability in an area, write the principle with "MUST implement" and reference a roadmap gap.
Mistake 2: Codifying Bad Patterns from the Codebase
Problem: Treating all existing patterns as worth preserving. The emergent ceiling captures whatever is in the codebase, including anti-patterns.
Why it's wrong: Some patterns in existing codebases are historical accidents, workarounds, or technical debt. Codifying them as principles locks in bad practices.
Fix: Only codify patterns that are intentionally good. Ask: "Would I recommend this pattern for a new project?" If no, it's technical debt, not an emergent ceiling pattern.
Mistake 3: Skipping Codebase Analysis
Problem: Writing the brownfield constitution without first running humaninloop:analysis-codebase.
Why it's wrong: Without analysis, the process devolves into guessing about existing patterns. Good patterns worth preserving get missed and essential floor status assessments become inaccurate.
Fix: Always run codebase analysis first. The analysis output has "Strengths to Preserve" (emergent ceiling input) and gap identification (essential floor status).
Mistake 4: Writing Aspirational Instead of Enforceable Principles
Problem: Writing principles like "Code SHOULD be clean" or "Security SHOULD be considered" without concrete enforcement.
Why it's wrong: These principles are unenforceable and untestable. They provide no governance value and will be ignored.
Fix: Every principle needs the Three-Part Rule from humaninloop:authoring-constitution: specific behavior, enforcement mechanism, and rationale. "Security SHOULD be considered" becomes "Authentication MUST use JWT with rotation, enforced by middleware check, because centralized auth prevents bypass."
Mistake 5: Ignoring Evolution Notes
Problem: Creating the constitution without documenting the brownfield context and gap status.
Why it's wrong: Future maintainers won't know which principles reflect existing capability vs. aspirational targets. They can't prioritize improvements.
Fix: Always include the Evolution Notes section with essential floor status table and link to evolution roadmap. This makes gaps visible and actionable.
Related Skills
- REQUIRED:
humaninloop:authoring-constitution - Core authoring (prerequisite)
- REQUIRED:
humaninloop:analysis-codebase - Analyze existing codebase before writing
- OPTIONAL:
humaninloop:validation-constitution - Quality validation (use after authoring)
- OPTIONAL:
humaninloop:authoring-roadmap - Create evolution roadmap for identified gaps
