mirror of
https://github.com/giuseppe-trisciuoglio/developer-kit.git
synced 2026-09-14 18:22:07 +08:00
feat(specs): added new skill constitution and remove hooks on stop
This commit is contained in:
Giuseppe Trisciuoglio
@@ -125,6 +125,15 @@ Transform ideas into production-ready code through a structured workflow:
|
||||
|
||||
|
||||
|
||||
#### Phase 0: Constitution (First-Time Setup)
|
||||
|
||||
| Command | When to Use | Output |
|
||||
|---------|-------------|--------|
|
||||
| `/developer-kit-specs:constitution create` | New project, before first spec | `docs/specs/constitution.md` |
|
||||
| `/developer-kit-specs:constitution check` | Validate spec/task against principles | Constitution Check Report |
|
||||
|
||||
The constitution defines the architectural DNA: approved stack, AI guardrails, security constraints (CWE mappings), and non-negotiable rules that govern all subsequent code generation.
|
||||
|
||||
#### Phase 1: Specification Creation
|
||||
|
||||
| Command | When to Use | Output |
|
||||
@@ -203,7 +212,7 @@ Always use constructor injection. Never use field injection with @Autowired.
|
||||
| Plugin | Language/Domain | Components | Description |
|
||||
|--------|-----------------|------------|-------------|
|
||||
| `developer-kit-core` | Core | 6 Agents, 8 Commands, 4 Skills | Required base plugin with general-purpose capabilities |
|
||||
| `developer-kit-specs` | Workflow | 9 Commands, 2 Skills | Specifications-driven development (SDD) workflow |
|
||||
| `developer-kit-specs` | Workflow | 9 Commands, 5 Skills | Specifications-driven development (SDD) workflow |
|
||||
| `developer-kit-java` | Java | 9 Agents, 11 Commands, 51 Skills, 4 Rules | Spring Boot, LangChain4J, AWS SDK, GraalVM |
|
||||
| `developer-kit-typescript` | TypeScript | 13 Agents, 3 Commands, 25 Skills, 17 Rules | NestJS, React, Next.js, Drizzle ORM, Monorepo |
|
||||
| `developer-kit-python` | Python | 4 Agents, 4 Rules | Django, Flask, FastAPI, AWS Lambda |
|
||||
|
||||
+10
-1
@@ -125,6 +125,15 @@ Developer Kit 提供**四层**能力：
|
||||
|
||||
|
||||
|
||||
#### 阶段 0：项目章程（首次设置）
|
||||
|
||||
| 命令 | 使用时机 | 输出 |
|
||||
|------|---------|------|
|
||||
| `/developer-kit-specs:constitution create` | 新项目，在第一个规范之前 | `docs/specs/constitution.md` |
|
||||
| `/developer-kit-specs:constitution check` | 根据原则验证规范/任务 | 章程检查报告 |
|
||||
|
||||
章程定义了架构 DNA：已批准的技术栈、AI 护栏、安全约束（CWE 映射）以及管理所有后续代码生成的不可协商规则。
|
||||
|
||||
#### 阶段 1：需求创建
|
||||
|
||||
| 命令 | 使用时机 | 输出 |
|
||||
@@ -203,7 +212,7 @@ globs: ["**/*.java"]
|
||||
| 插件 | 语言/领域 | 组件 | 描述 |
|
||||
|------|----------|------|------|
|
||||
| `developer-kit-core` | 核心 | 6 代理、8 命令、4 技能 | 包含通用能力的基础插件（必需） |
|
||||
| `developer-kit-specs` | 工作流 | 9 命令、2 技能 | 需求驱动开发（SDD）工作流 |
|
||||
| `developer-kit-specs` | 工作流 | 9 命令、5 技能 | 需求驱动开发（SDD）工作流 |
|
||||
| `developer-kit-java` | Java | 9 代理、11 命令、51 技能、4 规则 | Spring Boot、LangChain4J、AWS SDK、GraalVM |
|
||||
| `developer-kit-typescript` | TypeScript | 13 代理、3 命令、25 技能、17 规则 | NestJS、React、Next.js、Drizzle ORM、Monorepo |
|
||||
| `developer-kit-python` | Python | 4 代理、4 规则 | Django、Flask、FastAPI、AWS Lambda |
|
||||
|
||||
+10
-1
@@ -125,6 +125,15 @@ Transforma ideas en código listo para producción a través de un flujo de trab
|
||||
|
||||
|
||||
|
||||
#### Fase 0: Constitución (Configuración Inicial)
|
||||
|
||||
| Comando | Cuándo Usarlo | Salida |
|
||||
|---------|---------------|--------|
|
||||
| `/developer-kit-specs:constitution create` | Nuevo proyecto, antes de la primera spec | `docs/specs/constitution.md` |
|
||||
| `/developer-kit-specs:constitution check` | Validar spec/tarea contra los principios | Informe de Verificación Constitucional |
|
||||
|
||||
La constitución define el ADN arquitectónico: stack aprobado, guardrails de IA, restricciones de seguridad (mapeos CWE) y reglas no negociables que rigen toda la generación de código posterior.
|
||||
|
||||
#### Fase 1: Creación de Especificaciones
|
||||
|
||||
| Comando | Cuándo Usar | Salida |
|
||||
@@ -203,7 +212,7 @@ Usa siempre inyección por constructor. Nunca uses inyección de campo con @Auto
|
||||
| Plugin | Lenguaje/Dominio | Componentes | Descripción |
|
||||
|--------|------------------|-------------|-------------|
|
||||
| `developer-kit-core` | Core | 6 Agentes, 8 Comandos, 4 Habilidades | Plugin base requerido con capacidades de propósito general |
|
||||
| `developer-kit-specs` | Flujo de trabajo | 9 Comandos, 2 Habilidades | Flujo de trabajo de desarrollo guiado por especificaciones (SDD) |
|
||||
| `developer-kit-specs` | Flujo de trabajo | 9 Comandos, 5 Habilidades | Flujo de trabajo de desarrollo guiado por especificaciones (SDD) |
|
||||
| `developer-kit-java` | Java | 9 Agentes, 11 Comandos, 51 Habilidades, 4 Reglas | Spring Boot, LangChain4J, AWS SDK, GraalVM |
|
||||
| `developer-kit-typescript` | TypeScript | 13 Agentes, 3 Comandos, 25 Habilidades, 17 Reglas | NestJS, React, Next.js, Drizzle ORM, Monorepo |
|
||||
| `developer-kit-python` | Python | 4 Agentes, 4 Reglas | Django, Flask, FastAPI, AWS Lambda |
|
||||
|
||||
+10
-1
@@ -125,6 +125,15 @@ Trasforma le idee in codice production-ready attraverso un workflow strutturato:
|
||||
|
||||
|
||||
|
||||
#### Fase 0: Costituzione (Configurazione Iniziale)
|
||||
|
||||
| Comando | Quando Usarlo | Output |
|
||||
|---------|---------------|--------|
|
||||
| `/developer-kit-specs:constitution create` | Nuovo progetto, prima della prima spec | `docs/specs/constitution.md` |
|
||||
| `/developer-kit-specs:constitution check` | Valida spec/task rispetto ai principi | Report di Verifica Costituzionale |
|
||||
|
||||
La costituzione definisce il DNA architetturale: stack approvato, guardrail AI, vincoli di sicurezza (mappature CWE) e regole non negoziabili che governano tutta la generazione di codice successiva.
|
||||
|
||||
#### Fase 1: Creazione della Specifica
|
||||
|
||||
| Comando | Quando Usare | Output |
|
||||
@@ -203,7 +212,7 @@ Usa sempre l'iniezione tramite costruttore. Non usare mai l'iniezione su campo c
|
||||
| Plugin | Linguaggio/Dominio | Componenti | Descrizione |
|
||||
|--------|-------------------|------------|-------------|
|
||||
| `developer-kit-core` | Core | 6 Agent, 8 Comandi, 4 Skill | Plugin base richiesto con capacità generali |
|
||||
| `developer-kit-specs` | Workflow | 9 Comandi, 2 Skill | Workflow di sviluppo guidato dalle specifiche (SDD) |
|
||||
| `developer-kit-specs` | Workflow | 9 Comandi, 5 Skill | Workflow di sviluppo guidato dalle specifiche (SDD) |
|
||||
| `developer-kit-java` | Java | 9 Agent, 11 Comandi, 51 Skill, 4 Regole | Spring Boot, LangChain4J, AWS SDK, GraalVM |
|
||||
| `developer-kit-typescript` | TypeScript | 13 Agent, 3 Comandi, 25 Skill, 17 Regole | NestJS, React, Next.js, Drizzle ORM, Monorepo |
|
||||
| `developer-kit-python` | Python | 4 Agent, 4 Regole | Django, Flask, FastAPI, AWS Lambda |
|
||||
|
||||
@@ -34,6 +34,7 @@
|
||||
"./agents/session-tracking-agent.md"
|
||||
],
|
||||
"skills": [
|
||||
"./skills/constitution",
|
||||
"./skills/knowledge-graph",
|
||||
"./skills/ralph-loop",
|
||||
"./skills/specs-code-cleanup",
|
||||
|
||||
@@ -6,6 +6,7 @@ Specifications-driven development workflow for transforming ideas into functiona
|
||||
|
||||
This plugin provides a complete workflow for transforming ideas into implemented code:
|
||||
|
||||
- **Constitution**: Define the architectural DNA of the project — non-negotiable principles, approved stack, AI guardrails, and security constraints
|
||||
- **Brainstorming**: Transform ideas into pure functional specifications (WHAT, not HOW)
|
||||
- **Task Generation**: Convert functional specifications into executable tasks
|
||||
- **Task Management**: Add, split, update, and manage tasks
|
||||
@@ -20,6 +21,9 @@ This plugin provides a complete workflow for transforming ideas into implemented
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# 0. Define project constitution (once per project)
|
||||
/developer-kit-specs:constitution create
|
||||
|
||||
# 1. Create a functional specification
|
||||
/specs:brainstorm "Add user authentication with JWT tokens"
|
||||
|
||||
@@ -42,8 +46,8 @@ This plugin provides a complete workflow for transforming ideas into implemented
|
||||
## Workflow
|
||||
|
||||
```
|
||||
Idea → Functional Specification → Tasks → TDD / Implementation → Review → Cleanup → Done
|
||||
(brainstorm) (spec-to-tasks) (task-tdd) (task-review) (code-cleanup)
|
||||
Constitution → Idea → Functional Specification → Tasks → TDD / Implementation → Review → Cleanup → Done
|
||||
(constitution) (brainstorm) (spec-to-tasks) (task-tdd) (task-review) (code-cleanup)
|
||||
```
|
||||
|
||||
## Specification Structure
|
||||
@@ -67,6 +71,15 @@ docs/specs/001-user-auth/
|
||||
|
||||
## Commands
|
||||
|
||||
### Constitution
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/developer-kit-specs:constitution create` | Create `docs/specs/architecture.md` and/or `docs/specs/ontology.md` as project setup |
|
||||
| `/developer-kit-specs:constitution update --section=...` | Update a specific section of the constitution |
|
||||
| `/developer-kit-specs:constitution check --target=...` | Validate a spec/task/file against the constitution |
|
||||
| `/developer-kit-specs:constitution show` | Display the current constitution |
|
||||
|
||||
### Specification Creation
|
||||
|
||||
| Command | Description |
|
||||
@@ -348,6 +361,15 @@ Hooks automate task management:
|
||||
|
||||
## Skills
|
||||
|
||||
### constitution
|
||||
|
||||
Establishes and maintains the architectural DNA of a project through two shared documents:
|
||||
- `docs/specs/architecture.md` — approved stack, architectural rules, AI guardrails, security constraints (CWE mappings)
|
||||
- `docs/specs/ontology.md` — domain glossary (Ubiquitous Language), bounded contexts
|
||||
- Can be used **before brainstorm** as a project setup step
|
||||
- Provides `create`, `update`, `check`, and `show` operations
|
||||
- Constitution Check validates specs and tasks with CRITICAL / WARNING / OK severity levels
|
||||
|
||||
### knowledge-graph
|
||||
|
||||
Persistent JSON file that stores discoveries from codebase analysis:
|
||||
|
||||
@@ -4,6 +4,70 @@ Complete reference for all SDD commands with arguments, options, and real-world
|
||||
|
||||
---
|
||||
|
||||
## `/developer-kit-specs:constitution`
|
||||
|
||||
Establish and maintain the architectural DNA of a project through two shared documents: `docs/specs/architecture.md` (technology stack, rules, guardrails) and `docs/specs/ontology.md` (domain glossary / Ubiquitous Language). Can be used before `brainstorm` as a project setup step.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/developer-kit-specs:constitution [operation] [options]
|
||||
```
|
||||
|
||||
### Operations
|
||||
|
||||
| Operation | Description |
|
||||
|-----------|-------------|
|
||||
| `create` | Interactively create `docs/specs/architecture.md` and/or `docs/specs/ontology.md` |
|
||||
| `update` | Update a specific section of the existing constitution |
|
||||
| `check` | Validate a spec, task, or file against the constitution |
|
||||
| `show` | Display the current constitution |
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| `--section` | For `update` | Section to update: `stack`, `architecture`, `api`, `testing`, `security`, `guardrails` |
|
||||
| `--target` | For `check` | Path to the spec/task/file to validate |
|
||||
|
||||
### When to Use
|
||||
|
||||
- **`create`**: First step of any new SDD project — run before `brainstorm`
|
||||
- **`update`**: When technology choices or security requirements change
|
||||
- **`check`**: Before approving a spec or task plan; integrated into `task-review`
|
||||
- **`show`**: Quick reference during development
|
||||
|
||||
### Constitution Check Report
|
||||
|
||||
The `check` operation produces a report with three severity levels:
|
||||
|
||||
| Level | Meaning |
|
||||
|-------|---------|
|
||||
| `CRITICAL` | Violates a non-negotiable rule — must fix before proceeding |
|
||||
| `WARNING` | Deviates from a recommended practice — should fix |
|
||||
| `OK` | Compliant |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Create constitution for a new project (interactive)
|
||||
/developer-kit-specs:constitution create
|
||||
|
||||
# Validate a spec against the constitution
|
||||
/developer-kit-specs:constitution check --target=docs/specs/001-user-auth/2026-04-10--user-auth.md
|
||||
|
||||
# Validate a task plan
|
||||
/developer-kit-specs:constitution check --target=docs/specs/001-user-auth/tasks/TASK-003.md
|
||||
|
||||
# Update the security section
|
||||
/developer-kit-specs:constitution update --section=security
|
||||
|
||||
# Show current constitution
|
||||
/developer-kit-specs:constitution show
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:brainstorm`
|
||||
|
||||
Transform ideas into full functional specifications through guided brainstorming.
|
||||
|
||||
@@ -45,6 +45,18 @@ Verify installation:
|
||||
|
||||
Let's build a real feature: **user authentication with JWT tokens** for a Spring Boot application.
|
||||
|
||||
### Step 0: Establish the Constitution (once per project)
|
||||
|
||||
Before writing any specification, define the architectural DNA of your project:
|
||||
|
||||
```
|
||||
/developer-kit-specs:constitution create
|
||||
```
|
||||
|
||||
Claude will ask about your technology stack, architectural rules, and security constraints, then generate `docs/specs/architecture.md` and optionally `docs/specs/ontology.md`. These documents act as non-negotiable guardrails for all AI-generated code throughout the project lifecycle.
|
||||
|
||||
You only run `create` once. After that, use `check` to validate specs and tasks against them.
|
||||
|
||||
### Step 1: Brainstorm the Idea
|
||||
|
||||
```
|
||||
@@ -179,6 +191,8 @@ This detects deviations (scope expansions, refinements, reductions) and updates
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/developer-kit-specs:constitution create` | Define project architectural DNA (run once) |
|
||||
| `/developer-kit-specs:constitution check --target=file` | Validate spec/task against constitution |
|
||||
| `/specs:brainstorm "idea"` | Create a full specification |
|
||||
| `/specs:quick-spec "fix"` | Create a minimal spec for small changes |
|
||||
| `/specs:spec-to-tasks --lang=spring spec/` | Generate executable tasks |
|
||||
|
||||
@@ -19,6 +19,9 @@ Every change should update all three vertices. The sync commands keep them align
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Phase 0: CONSTITUTION (first time only) │
|
||||
│ constitution create → defines architectural DNA of the project │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ Phase 1: SPECIFICATION │
|
||||
│ brainstorm → spec-quality-check → spec-to-tasks │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
@@ -35,6 +38,35 @@ Every change should update all three vertices. The sync commands keep them align
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Constitution (First-Time Setup)
|
||||
|
||||
Before writing any specification, establish the **architectural DNA** of your project:
|
||||
|
||||
```
|
||||
/developer-kit-specs:constitution create
|
||||
```
|
||||
|
||||
This creates `docs/specs/architecture.md` (and optionally `docs/specs/ontology.md`) — documents that define:
|
||||
- Approved technology stack and forbidden libraries
|
||||
- Architectural rules (e.g., constructor injection, no field injection)
|
||||
- API standards and authentication approach
|
||||
- Security constraints with CWE mappings
|
||||
- AI guardrails that govern all subsequent code generation
|
||||
|
||||
**You only run `create` once per project.** After that, use `update` to evolve them and `check` to validate specs/tasks against them.
|
||||
|
||||
```
|
||||
# Validate a spec against the constitution
|
||||
/developer-kit-specs:constitution check --target=docs/specs/001-user-auth/2026-04-10--user-auth.md
|
||||
|
||||
# Update a section
|
||||
/developer-kit-specs:constitution update --file=architecture --section=security
|
||||
```
|
||||
|
||||
The constitution feeds into every subsequent phase — brainstorm, spec-to-tasks, task-implementation, and task-review all respect its guardrails.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Specification
|
||||
|
||||
### 1.1 Choose Your Entry Point
|
||||
|
||||
@@ -1,19 +1,6 @@
|
||||
{
|
||||
"description": "Developer Kit Specs hooks: Drift Guard for spec fidelity, Task Auto-Status for automatic frontmatter management, Task KPI Analyzer for quality metrics, and Session Tracking Hook for audit trail logging",
|
||||
"hooks": {
|
||||
"Stop": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "agent",
|
||||
"prompt": "You are the session-tracking-agent. Your job is to generate or update a session tracking entry in tracking_log.md at the project root.\n\nStop event payload:\n$ARGUMENTS\n\nProcess:\n1. Parse the event payload to extract session_id, transcript_path, cwd, and last_assistant_message.\n2. If stop_hook_active is true, exit immediately to prevent re-entrant activation.\n3. Read only the LAST 100 lines of the transcript JSONL file (transcript_path).\n4. Derive the change rationale from conversational context — explain WHY changes were made, not just WHAT changed.\n5. Get the current git branch using Bash(git:*).\n6. Use the first 8 characters of session_id as SHORT_ID (idempotency key).\n7. If an entry with this SHORT_ID already exists in tracking_log.md, UPDATE it. Otherwise, ADD a new entry at the TOP of the file.\n8. If no meaningful file changes occurred in this response, do NOT write anything.\n9. NEVER include credentials, API keys, tokens, or passwords in the log.\n\nEntry format:\n## YYYY-MM-DD — Session SHORT_ID\n**Branch:** branch-name\n**Orario:** HH:MM\n\n### Task eseguiti\n- description\n\n### File modificati\n- path/to/file (creato | modificato | eliminato)\n\n### Rationale\nWhy the changes were made.\n\n### Commit (only if commits were made)\n- short-hash message",
|
||||
"model": "sonnet",
|
||||
"async": true,
|
||||
"timeout": 60
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
|
||||
@@ -0,0 +1,279 @@
|
||||
---
|
||||
name: constitution
|
||||
description: "Establishes and maintains the architectural DNA of a project through two shared documents: docs/specs/architecture.md (technology and infrastructure choices) and docs/specs/ontology.md (domain glossary / Ubiquitous Language). Can be used BEFORE brainstorm as a project setup step, or at any point in the SDD lifecycle. Triggers on 'create constitution', 'update constitution', 'constitution check', 'validate against constitution', 'project principles', 'architectural guardrails', 'setup project architecture', 'define ontology'."
|
||||
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion, TodoWrite
|
||||
---
|
||||
|
||||
# Constitution Skill
|
||||
|
||||
## Overview
|
||||
|
||||
The **Constitution** is the architectural DNA of a project, expressed through two shared documents:
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `docs/specs/architecture.md` | Technology stack, infrastructure choices, architectural rules, security constraints, AI guardrails |
|
||||
| `docs/specs/ontology.md` | Domain glossary (Ubiquitous Language) — terms, definitions, bounded contexts |
|
||||
|
||||
These files live at the `docs/specs/` level and are **shared across all specifications**.
|
||||
|
||||
**Key difference from the old constitution.md approach**: instead of a single monolithic file, the constitution is split into two focused documents that are also created and enriched by `brainstorm` (Phase 6.8.6) and `spec-to-tasks` (Phase 1.5). This skill lets you create or manage them **before brainstorm**, as a project setup step.
|
||||
|
||||
## When to Use
|
||||
|
||||
| Scenario | Operation |
|
||||
|----------|-----------|
|
||||
| New project — define stack and domain language before first brainstorm | `create` |
|
||||
| Stack or security rules changed | `update` |
|
||||
| Validate a spec, task, or file against architecture and ontology | `check` |
|
||||
| Review current architecture and ontology | `show` |
|
||||
|
||||
**Trigger phrases:**
|
||||
- "Create constitution", "Setup project architecture", "Define ontology"
|
||||
- "Update constitution", "Update architecture", "Update ontology"
|
||||
- "Constitution check", "Validate against constitution"
|
||||
- "Show constitution", "Project principles", "Architectural guardrails"
|
||||
|
||||
## Available Operations
|
||||
|
||||
**1. create** — Create one or both files interactively
|
||||
**2. update** — Update a specific section of one file
|
||||
**3. check** — Validate a spec/task/file against both documents
|
||||
**4. show** — Display the current state of both documents
|
||||
|
||||
---
|
||||
|
||||
## Operation: create
|
||||
|
||||
1. Ask the user which files to create (if not specified in `$ARGUMENTS`):
|
||||
- Options: "Both architecture.md and ontology.md" (recommended), "architecture.md only", "ontology.md only"
|
||||
|
||||
2. For each file to create, check if it already exists. If yes, ask: overwrite or skip.
|
||||
|
||||
3. **For `docs/specs/architecture.md`**, gather via `AskUserQuestion`:
|
||||
|
||||
**Q1 — Software Stack**:
|
||||
- Options: "Java / Spring Boot", "TypeScript / NestJS", "TypeScript / React", "Python / Django or FastAPI", "PHP / Laravel or Symfony", or freeform
|
||||
|
||||
**Q2 — Data Architecture**:
|
||||
- Options: "PostgreSQL", "MySQL", "MongoDB", "Multiple databases", or freeform
|
||||
|
||||
**Q3 — Infrastructure**:
|
||||
- Options: "AWS", "Docker / Docker Compose", "Kubernetes", "Serverless", "Not yet decided", or freeform
|
||||
|
||||
**Q4 — Architectural Rules** (optional, freeform):
|
||||
- Forbidden patterns, required patterns, security constraints, AI guardrails
|
||||
|
||||
Then create `docs/specs/architecture.md` using the **Architecture Template** below.
|
||||
|
||||
4. **For `docs/specs/ontology.md`**, gather via `AskUserQuestion`:
|
||||
|
||||
Ask the user to list the main domain terms and their definitions. Explain:
|
||||
> "The ontology captures the Ubiquitous Language of your project. It is normally enriched during brainstorming when terms emerge from the idea. You can seed it now with known terms, or create an empty scaffold to fill later."
|
||||
|
||||
- Options: "Seed with known terms (I'll provide them)", "Create empty scaffold", "Skip for now"
|
||||
|
||||
Then create `docs/specs/ontology.md` using the **Ontology Template** below.
|
||||
|
||||
5. Confirm with the user before writing each file.
|
||||
|
||||
---
|
||||
|
||||
## Operation: update
|
||||
|
||||
1. Identify the target file and section from `$ARGUMENTS`:
|
||||
- `--file=architecture` or `--file=ontology`
|
||||
- `--section=<section-name>` (e.g., `--section=security`, `--section=glossary`)
|
||||
2. Read the target file.
|
||||
3. Apply the update surgically — do not touch other sections.
|
||||
4. Update the `Last Updated` date.
|
||||
5. Write the updated file.
|
||||
|
||||
---
|
||||
|
||||
## Operation: check
|
||||
|
||||
1. Read both `docs/specs/architecture.md` and `docs/specs/ontology.md`. If either is missing, warn the user but continue with the available file(s).
|
||||
2. Read the target file from `$ARGUMENTS` (`--target=<path>`).
|
||||
3. Check against **architecture.md**:
|
||||
- Forbidden libraries/imports present?
|
||||
- Unapproved patterns used?
|
||||
- Security constraints violated (raw SQL, hardcoded secrets, etc.)?
|
||||
- AI guardrails violated?
|
||||
4. Check against **ontology.md**:
|
||||
- Are domain terms used consistently (no synonyms for defined terms)?
|
||||
- Are new domain concepts introduced without being added to the glossary?
|
||||
5. Output a **Constitution Check Report** (see format below).
|
||||
|
||||
---
|
||||
|
||||
## Operation: show
|
||||
|
||||
1. Read `docs/specs/architecture.md` and `docs/specs/ontology.md`.
|
||||
2. Print both files formatted for readability, with a header indicating which file is which.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Template
|
||||
|
||||
```markdown
|
||||
# Project Architecture
|
||||
|
||||
**Created**: YYYY-MM-DD
|
||||
**Last Updated**: YYYY-MM-DD
|
||||
|
||||
## Software Stack
|
||||
|
||||
| Component | Technology | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| Language | [e.g., TypeScript] | [version if known] |
|
||||
| Framework | [e.g., NestJS] | [version if known] |
|
||||
| Key Libraries | [e.g., Drizzle ORM, Passport] | |
|
||||
|
||||
## Data Architecture
|
||||
|
||||
| Component | Technology | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| Primary Database | [e.g., PostgreSQL] | |
|
||||
| Caching | [e.g., Redis, none] | |
|
||||
| ORM / Data Access | [e.g., Drizzle, Hibernate] | |
|
||||
| Migrations | [e.g., Flyway, Drizzle Kit] | |
|
||||
|
||||
## Infrastructure
|
||||
|
||||
| Component | Technology | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| Hosting | [e.g., AWS ECS] | |
|
||||
| CI/CD | [e.g., GitHub Actions] | |
|
||||
| Containerization | [e.g., Docker] | |
|
||||
| Orchestration | [e.g., Kubernetes, none] | |
|
||||
|
||||
## Architectural Rules
|
||||
|
||||
- [Rule 1, e.g., "Use constructor injection. Never use @Autowired on fields."]
|
||||
- [Rule 2, e.g., "Domain entities must not depend on framework annotations."]
|
||||
|
||||
## Security Constraints
|
||||
|
||||
- Forbidden patterns:
|
||||
- No raw SQL string concatenation (SQL injection — CWE-89)
|
||||
- No hardcoded secrets or credentials (CWE-798)
|
||||
- No deserialization of untrusted data (CWE-502)
|
||||
- Required patterns:
|
||||
- [e.g., All inputs validated with Bean Validation]
|
||||
- [e.g., All secrets via environment variables or Secrets Manager]
|
||||
|
||||
## AI Guardrails
|
||||
|
||||
Rules that AI agents MUST follow when generating code for this project:
|
||||
|
||||
- [Guardrail 1, e.g., "Never generate @Transactional on repository methods."]
|
||||
- [Guardrail 2, e.g., "Always generate tests alongside implementation code."]
|
||||
- [Guardrail 3, e.g., "Do not introduce new dependencies without explicit approval."]
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
> Significant modifications to this architecture document must be tracked
|
||||
> via **ADR (Architecture Decision Records)** using the `adr-drafting` skill.
|
||||
>
|
||||
> ADR location: `docs/architecture/adr/`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ontology Template
|
||||
|
||||
```markdown
|
||||
# Project Ontology — Ubiquitous Language
|
||||
|
||||
**Created**: YYYY-MM-DD
|
||||
**Last Updated**: YYYY-MM-DD
|
||||
|
||||
## Domain Glossary
|
||||
|
||||
| Term | Definition | Bounded Context |
|
||||
|------|-----------|-----------------|
|
||||
| [Term 1] | [Definition] | [Context where this term applies] |
|
||||
| [Term 2] | [Definition] | [Context where this term applies] |
|
||||
|
||||
## Bounded Contexts
|
||||
|
||||
| Context | Description | Key Terms |
|
||||
|---------|-------------|-----------|
|
||||
| [Context 1] | [Description] | [Key terms] |
|
||||
|
||||
## Conceptual Mapping
|
||||
|
||||
[Relationships between key domain entities — to be refined during brainstorming and task generation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Constitution Check Report Format
|
||||
|
||||
```
|
||||
## Constitution Check Report
|
||||
Target: <file or spec path>
|
||||
Date: YYYY-MM-DD
|
||||
|
||||
### Architecture Check
|
||||
|
||||
| Rule | Status | Detail |
|
||||
|------|--------|--------|
|
||||
| Constructor injection required | ✅ OK | No field injection found |
|
||||
| No hardcoded secrets | ❌ CRITICAL | Line 42: hardcoded password string |
|
||||
| JWT authentication | ⚠️ WARNING | Missing @PreAuthorize on endpoint |
|
||||
|
||||
### Ontology Check
|
||||
|
||||
| Term | Status | Detail |
|
||||
|------|--------|--------|
|
||||
| "Reservation" used consistently | ✅ OK | No synonym "Booking" found |
|
||||
| New term "Voucher" introduced | ⚠️ WARNING | Not defined in ontology.md |
|
||||
|
||||
### Summary
|
||||
- CRITICAL violations: 1 (must fix before proceeding)
|
||||
- WARNING violations: 2 (should fix)
|
||||
- Compliant rules: 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Relationship with brainstorm and spec-to-tasks
|
||||
|
||||
This skill is the **pre-brainstorm setup** entry point. The same files are also created/enriched by:
|
||||
|
||||
| Command | When | What it does |
|
||||
|---------|------|-------------|
|
||||
| `constitution create` | Before brainstorm (this skill) | Creates architecture.md and/or ontology.md from scratch |
|
||||
| `brainstorm` Phase 6.8.6 | During brainstorming | Creates/enriches ontology.md with terms extracted from the idea |
|
||||
| `spec-to-tasks` Phase 1.5 | After brainstorm | Creates architecture.md if missing; enriches ontology.md with new terms from the spec |
|
||||
|
||||
**If you run `constitution create` before brainstorm**, the brainstorm and spec-to-tasks commands will detect the existing files and load them instead of creating new ones — no duplication.
|
||||
|
||||
**Note on ontology.md**: The ontology is normally most naturally created during brainstorming, because domain terms emerge from the idea description. Using `constitution create` to seed it beforehand is useful when the team already has a well-defined domain language.
|
||||
|
||||
---
|
||||
|
||||
## Integration with SDD Workflow
|
||||
|
||||
```
|
||||
[Optional] constitution create ← this skill (pre-brainstorm setup)
|
||||
↓
|
||||
brainstorm ← enriches ontology.md (Phase 6.8.6)
|
||||
↓
|
||||
spec-to-tasks ← loads/creates architecture.md, enriches ontology.md (Phase 1.5)
|
||||
↓
|
||||
task-implementation ← AI guardrails from architecture.md prevent unapproved patterns
|
||||
↓
|
||||
task-review / ralph-loop ← constitution check validates implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Does NOT modify source code** — only creates/updates `docs/specs/architecture.md` and `docs/specs/ontology.md`
|
||||
- **Constitution Check is advisory for WARNINGs** — CRITICAL violations must be resolved
|
||||
- **One architecture.md and one ontology.md per project** — shared across all specs
|
||||
- **Version the architecture** — update `Last Updated` date on every change; use ADRs for significant decisions
|
||||
Reference in New Issue
Block a user