project-constitution

name	project-constitution
description	Run project context preflight before /opsx workflows or substantial project work. Use to read CONSTITUTION.md, handle missing constitution/bootstrap or legacy PROJECT_CONSTITUTION.md migration, load architecture context, enforce project rules, and protect local secrets.
license	MIT
compatibility	Codex skill for intent-driven OpenSpec projects.

Project Context Preflight

Run this preflight before any /opsx:* workflow action or direct openspec-* skill invocation that changes, verifies, archives, syncs, or otherwise relies on project state.

CONSTITUTION.md is persistent Git-tracked project context. It is not an OpenSpec artifact and is not archived with changes. OpenSpec CLI itself does not read it; Codex is responsible for reading and enforcing it.

For terminology-sensitive work, read root CONTEXT.md or CONTEXT-MAP.md when present. For architecture-sensitive work, also read root ARCHITECTURE.md, adr/README.md, and relevant in-force adr/*.md files. ARCHITECTURE.md is a current snapshot; durable rationale remains in ADRs.

Preflight Inputs

• Repository root.
• User request and target workflow/action.
• OpenSpec change name, when applicable.
• Current OpenSpec artifacts relevant to the action, when applicable.

Steps

1. Resolve repository root

   Run git rev-parse --show-toplevel when available and operate from that root. If the command fails, use the current working directory and say that repository-root detection was unavailable.

2. Check for CONSTITUTION.md

   Look for CONSTITUTION.md in the repository root.

   If the file exists:

   • read it before taking the workflow action;
   • summarize only the relevant non-secret rules when reporting;
   • continue to conflict, architecture, and secret checks.

   If CONSTITUTION.md is missing but legacy PROJECT_CONSTITUTION.md exists:

   • report that CONSTITUTION.md is the canonical filename;
   • treat PROJECT_CONSTITUTION.md only as migration input;
   • offer to rename or migrate it;
   • do not maintain both files as competing active rule sources.

   If no constitution exists:

   • report that the project constitution is missing;
   • offer to create CONSTITUTION.md from the template/start file expected by this overlay;
   • allow only bootstrap-safe or diagnostic actions unless the user gives an explicit one-time override.

3. Apply the missing-constitution bootstrap rule

   Without CONSTITUTION.md, continue only when the action is one of:

   • exploration/read-only explanation;
   • creating or migrating CONSTITUTION.md;
   • creating or repairing ARCHITECTURE.md or project context docs;
   • overlay health diagnostics such as /opsx:check-overlay;
   • a strictly constitution/project-context bootstrap change.

   A project-context bootstrap change is allowed only when all are true:

   • the change name or user request is explicitly about constitution, architecture context, or setup, such as formalize-project-context-architecture, add-project-constitution, initialize-project-constitution, or update-project-constitution-template;
   • the next action only creates or edits constitution/bootstrap artifacts, templates, prompts, skills, docs, safe setup checks, or architecture context files;
   • the action does not implement unrelated product behavior, access external systems, sync specs, archive, or run bulk workflows.

Output Guidance

When the preflight succeeds, mention only the relevant rule categories that matter to the current action. Keep the output concise.

When the preflight stops, report:

• blocker;
• relevant constitution/architecture rule or missing file;
• trusted state;
• files changed so far, if any;
• recommended next user action.

Guardrails

• Do not patch or fork OpenSpec CLI.
• Do not treat CONSTITUTION.md or ARCHITECTURE.md as OpenSpec change artifacts.
• Do not archive CONSTITUTION.md, ARCHITECTURE.md, or local secret files with OpenSpec changes.
• Do not stage or commit .secrets.local.env or any local secret file.
• Do not reveal secret values, even when debugging.
• Do not proceed through a material constitution or architecture conflict without user input or an explicit one-time override.
• A one-time override does not disable future context checks.