stack-orchestrator/AI-FRIENDLY-PLAN.md

Plan: Make Stack-Orchestrator AI-Friendly

Goal

Make the stack-orchestrator repository easier for AI tools (Claude Code, Cursor, Copilot) to understand and use for generating stacks, including adding a create-stack command.

---

Part 1: Documentation & Context Files

1.1 Add CLAUDE.md

Create a root-level context file for AI assistants.

File: CLAUDE.md

Contents:

• Project overview (what stack-orchestrator does)
• Stack creation workflow (step-by-step)
• File naming conventions
• Required vs optional fields in stack.yml
• Common patterns and anti-patterns
• Links to example stacks (simple, medium, complex)

1.2 Add JSON Schema for stack.yml

Create formal validation schema.

File: schemas/stack-schema.json

Benefits:

• AI tools can validate generated stacks
• IDEs provide autocomplete
• CI can catch errors early

1.3 Add Template Stack with Comments

Create an annotated template for reference.

File: stack_orchestrator/data/stacks/_template/stack.yml

# Stack definition template - copy this directory to create a new stack
version: "1.2"  # Required: 1.0, 1.1, or 1.2
name: my-stack  # Required: lowercase, hyphens only
description: "Human-readable description"  # Optional
repos:          # Git repositories to clone
  - github.com/org/repo
containers:     # Container images to build (must have matching container-build/)
  - cerc/my-container
pods:           # Deployment units (must have matching docker-compose-{pod}.yml)
  - my-pod

1.4 Document Validation Rules

Create explicit documentation of constraints currently scattered in code.

File: docs/stack-format.md

Contents:

• Container names must start with cerc/
• Pod names must match compose file: docker-compose-{pod}.yml
• Repository format: host/org/repo[@ref]
• Stack directory name should match name field
• Version field options and differences

---

Part 2: Add create-stack Command

2.1 Command Overview

laconic-so create-stack --repo github.com/org/my-app [--name my-app] [--type webapp]

Behavior:

1. Parse repo URL to extract app name (if --name not provided)
2. Create stacks/{name}/stack.yml
3. Create container-build/cerc-{name}/Dockerfile and build.sh
4. Create compose/docker-compose-{name}.yml
5. Update list files (repository-list.txt, container-image-list.txt, pod-list.txt)

2.2 Files to Create

File	Purpose
stack_orchestrator/create/__init__.py	Package init
stack_orchestrator/create/create_stack.py	Command implementation

2.3 Files to Modify

File	Change
stack_orchestrator/main.py	Add import and cli.add_command()

2.4 Command Options

Option	Required	Description
--repo	Yes	Git repository URL (e.g., github.com/org/repo)
--name	No	Stack name (defaults to repo name)
--type	No	Template type: webapp, service, empty (default: webapp)
--force	No	Overwrite existing files

2.5 Template Types

Type	Base Image	Port	Use Case
webapp	node:20-bullseye-slim	3000	React/Vue/Next.js apps
service	python:3.11-slim	8080	Python backend services
empty	none	none	Custom from scratch

---

Part 3: Implementation Summary

New Files (6)

1. CLAUDE.md - AI assistant context
2. schemas/stack-schema.json - Validation schema
3. stack_orchestrator/data/stacks/_template/stack.yml - Annotated template
4. docs/stack-format.md - Stack format documentation
5. stack_orchestrator/create/__init__.py - Package init
6. stack_orchestrator/create/create_stack.py - Command implementation

Modified Files (1)

1. stack_orchestrator/main.py - Register create-stack command

---

Verification

# 1. Command appears in help
laconic-so --help | grep create-stack

# 2. Dry run works
laconic-so --dry-run create-stack --repo github.com/org/test-app

# 3. Creates all expected files
laconic-so create-stack --repo github.com/org/test-app
ls stack_orchestrator/data/stacks/test-app/
ls stack_orchestrator/data/container-build/cerc-test-app/
ls stack_orchestrator/data/compose/docker-compose-test-app.yml

# 4. Build works with generated stack
laconic-so --stack test-app build-containers