Ggen rdf integration #1365
Open
Ggen rdf integration #1365
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Integrate ggen v6 RDF-first architecture into spec-kit, enabling deterministic
ontology-driven specification generation following the constitutional equation:
spec.md = μ(feature.ttl)
## Core Architecture Changes
### 1. Constitutional Equation
- TTL files (Turtle/RDF) are the source of truth
- Markdown files are generated artifacts (never manually edited)
- SHACL shapes enforce constraints
- Idempotent transformations (μ∘μ = μ)
- Cryptographic provenance receipts
### 2. Infrastructure Updates
**Scripts (RDF-first support):**
- `scripts/bash/check-prerequisites.sh` - Returns TTL paths as primary sources
- Detects RDF vs. legacy features (checks ontology/ + ggen.toml)
- Validates TTL files first, falls back to MD for backward compatibility
- JSON output includes: TTL_SOURCES, ONTOLOGY_DIR, GENERATED_DIR
- `scripts/bash/common.sh` - Extended path variables for RDF architecture
- Added TTL source paths: FEATURE_SPEC_TTL, IMPL_PLAN_TTL, TASKS_TTL
- Added generated paths: ontology/, generated/, templates/
- SPECIFY_FEATURE env var support for exact branch matching
- `scripts/bash/setup-plan.sh` - Creates plan.ttl from templates
- Auto-detects RDF-first features
- Creates ontology/plan.ttl from template
- Symlinks templates/plan.tera
- Maintains backward compatibility for legacy MD-based features
### 3. Tera Templates (Markdown Generation)
**New templates for RDF → Markdown transformation:**
- `templates/plan.tera` (151 lines) - Renders plan.md from plan.ttl
- Technology stack, phases, decisions, risks, dependencies
- `templates/tasks.tera` (148 lines) - Renders tasks.md from tasks.ttl
- Phase-based organization, dependency tracking, parallelization
- `templates/constitution.tera` (173 lines) - Renders constitution.md
- Core principles, build standards, workflow rules, governance
### 4. RDF Helper Templates (Turtle/RDF Sources)
**Complete TTL template library (10 templates):**
- `templates/rdf-helpers/user-story.ttl.template` - User story instances with acceptance scenarios
- `templates/rdf-helpers/functional-requirement.ttl.template` - Functional requirements
- `templates/rdf-helpers/success-criterion.ttl.template` - Success criteria with metrics
- `templates/rdf-helpers/entity.ttl.template` - Domain entity definitions
- `templates/rdf-helpers/edge-case.ttl.template` - Edge case scenarios (NEW)
- `templates/rdf-helpers/assumption.ttl.template` - Assumption instances (NEW)
- `templates/rdf-helpers/plan-decision.ttl.template` - Architectural decisions (NEW)
- `templates/rdf-helpers/task.ttl.template` - Individual task instances (NEW)
- `templates/rdf-helpers/plan.ttl.template` - Complete plan structure (NEW, 2.3KB)
- `templates/rdf-helpers/tasks.ttl.template` - Complete task breakdown (NEW, 3.1KB)
### 5. Documentation
**Comprehensive RDF workflow documentation:**
- `docs/RDF_WORKFLOW_GUIDE.md` (19KB) - Complete workflow guide
- Constitutional equation explanation
- Five-stage pipeline (μ₁→μ₂→μ₃→μ₄→μ₅)
- SHACL validation guide with error examples
- Template system explanation
- Troubleshooting common issues
- End-to-end examples
- `docs/GGEN_RDF_README.md` - ggen-specific RDF integration overview
## Key Features
### SHACL Validation
- Priority values MUST be "P1", "P2", or "P3" (SHACL enforced)
- Dates in YYYY-MM-DD format with ^^xsd:date
- User stories require minimum 1 acceptance scenario
- Automatic validation during ggen render
### Five-Stage Pipeline
1. **μ₁ (Normalization)** - Canonicalize RDF + SHACL validation
2. **μ₂ (Extraction)** - SPARQL queries extract data
3. **μ₃ (Emission)** - Tera templates render markdown
4. **μ₄ (Canonicalization)** - Format markdown
5. **μ₅ (Receipt)** - Generate cryptographic hash
### Backward Compatibility
- Legacy MD-based features continue to work
- Auto-detection of RDF vs. legacy format
- Graceful fallback when TTL files missing
- SPECIFY_FEATURE env var for multi-feature branches
## Directory Structure (RDF-first features)
```
specs/NNN-feature-name/
├── ontology/ # SOURCE OF TRUTH
│ ├── feature-content.ttl
│ ├── plan.ttl
│ ├── tasks.ttl
│ └── spec-kit-schema.ttl (symlink)
├── generated/ # GENERATED ARTIFACTS
│ ├── spec.md
│ ├── plan.md
│ └── tasks.md
├── templates/ # TERA TEMPLATES (symlinks)
│ ├── spec.tera
│ ├── plan.tera
│ └── tasks.tera
├── ggen.toml # GGEN V6 CONFIG
└── checklists/
└── requirements.md
```
## Usage Examples
### Create RDF-first specification:
```bash
/speckit.specify "Add TTL validation command"
# Creates: ontology/feature-content.ttl
# Edit TTL source
vim specs/005-feature/ontology/feature-content.ttl
# Validate against SHACL
ggen validate ontology/feature-content.ttl --shapes ontology/spec-kit-schema.ttl
# Generate markdown
ggen render templates/spec.tera ontology/feature-content.ttl > generated/spec.md
```
### Create implementation plan:
```bash
/speckit.plan
# Creates: ontology/plan.ttl
# Generate markdown
ggen render templates/plan.tera ontology/plan.ttl > generated/plan.md
```
### Create task breakdown:
```bash
/speckit.tasks
# Creates: ontology/tasks.ttl
# Generate markdown
ggen render templates/tasks.tera ontology/tasks.ttl > generated/tasks.md
```
## Integration Notes
This branch integrates ggen v6's RDF-first architecture into spec-kit, enabling:
- Deterministic specification generation
- SHACL-enforced quality constraints
- Cryptographic provenance tracking
- Idempotent transformations
- Complete Turtle/RDF template library
For complete workflow documentation, see: docs/RDF_WORKFLOW_GUIDE.md
🤖 Generated with ggen v6 ontology-driven specification system
Add spec-kit-schema.ttl (25KB) containing SHACL shapes for validating: - User story priorities (must be P1, P2, or P3) - Feature metadata (dates, status, required fields) - Acceptance scenarios (min 1 per user story) - Task dependencies and parallelization - Entity definitions and requirements This schema enforces quality constraints during ggen render operations.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.