Authors constitutions for existing codebases using Essential Floor for governance and Emergent Ceiling to codify patterns. For brownfield projects after codebase analysis.
From humaninloopnpx claudepluginhub deepeshbodh/human-in-loop --plugin humaninloopThis skill uses the workspace's default tool permissions.
references/EMERGENT-CEILING-PATTERNS.mdreferences/ESSENTIAL-FLOOR.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
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.
Applicable when:
humaninloop:authoring-constitution directlyhumaninloop:analysis-codebase firsthumaninloop:validation-constitutionREQUIRED: This skill extends humaninloop:authoring-constitution. Prerequisites for brownfield mode:
humaninloop:authoring-constitution for the Three-Part Principle Rule (Enforcement, Testability, Rationale)humaninloop:authoring-constitutionhumaninloop:authoring-constitutionhumaninloop:analysis-codebase to understand existing patternsBrownfield constitutions follow all rules from humaninloop:authoring-constitution, plus additional guidance for existing codebases.
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:
Beyond the essential floor, identify existing good patterns worth codifying:
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 |
# [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.
Additional checks for brownfield constitutions (beyond standard checklist):
After completing brownfield constitution, run validation using humaninloop:validation-constitution.
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.
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.
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).
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."
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.
humaninloop:authoring-constitution - Core authoring (prerequisite)humaninloop:analysis-codebase - Analyze existing codebase before writinghumaninloop:validation-constitution - Quality validation (use after authoring)humaninloop:authoring-roadmap - Create evolution roadmap for identified gaps