specsmd 0.0.1

package/flows/aidlc/skills/operations/build.md

@@ -0,0 +1,237 @@
+# Skill: Build Deployment Artifacts
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Operations Progress
+- [ ] Build approval  ← current
+- [ ] Staging deploy
+- [ ] Production deploy
+- [ ] Monitoring setup
+```
+
+---
+
+## Checkpoints in This Skill
+
+| Checkpoint | Purpose | Wait For |
+|------------|---------|----------|
+| Checkpoint 1 | Build approval | User confirmation |
+
+---
+
+## Goal
+
+Create deployable packages (containers, functions, bundles) for a Unit and document the build metadata.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to build
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--version` - Explicit version tag (default: auto-generate)
+
+---
+
+## Process
+
+### 1. Verify Prerequisites
+
+Check construction completion:
+
+- [ ] **All bolts complete**: Path from `schema.bolts` (Required)
+- [ ] **Tests passing**: Last bolt test stage (Required)
+- [ ] **Code exists**: Unit source directory (Required)
+
+### 2. Detect Build Type
+
+Analyze unit structure to determine build strategy:
+
+- `Dockerfile` → **Container** → `docker build`
+- `serverless.yml` → **Serverless** → Framework deploy
+- `package.json` → **Node.js** → `npm run build`
+- `Cargo.toml` → **Rust** → `cargo build --release`
+- `go.mod` → **Go** → `go build`
+
+### 3. Determine Version
+
+Generate semantic version:
+
+```markdown
+## Version Calculation
+
+Base: {major}.{minor}.{patch}
+Commit: {short-sha}
+Tag: v{version}-{commit}
+
+Example: v1.2.0-abc123
+```
+
+### 4. Execute Build
+
+Run appropriate build commands:
+
+1. **Pre-build**: Install dependencies
+2. **Build**: Compile/bundle
+3. **Test**: Run final verification
+4. **Package**: Create deployable artifact
+5. **Tag**: Apply version tag
+
+### 5. Push to Registry
+
+Upload artifact to configured registry:
+
+- Container → Container registry
+- Package → Package registry
+- Function → Function storage
+
+### 6. Document Build
+
+Create/update `deployment/build.md`:
+
+```markdown
+---
+version: {version}
+commit: {sha}
+built: {timestamp}
+status: success
+---
+
+## Build: {version}
+
+### Artifact
+- **Type**: {container|function|package}
+- **Tag**: `{registry}/{unit}:{version}`
+- **Size**: {size}
+- **SHA**: {artifact-sha}
+
+### Build Environment
+- OS: {os}
+- Runtime: {runtime-version}
+- Builder: {tool-version}
+
+### Dependencies
+
+- **{dep1}**: {ver}
+- **{dep2}**: {ver}
+
+### Build Log Summary
+{key events from build}
+```
+
+---
+
+## Output
+
+````markdown
+## Build Complete: {unit-name}
+
+### Artifact Created
+
+- **Version**: `{version}`
+- **Tag**: `{registry}/{unit}:{version}`
+- **Built**: {timestamp}
+- **Size**: {size}
+
+### Build Summary
+- Dependencies: {count} packages
+- Build time: {duration}
+- Tests: ✅ All passing
+
+### Artifact Location
+```text
+{registry-url}/{unit}:{version}
+```
+
+### Documentation Updated
+
+- `{unit-path}/deployment/build.md`
+
+### Actions
+
+1 - **deploy**: Deploy to dev environment
+2 - **menu**: Return to operations menu
+
+### Suggested Next Step
+
+→ **deploy** - Deploy `{version}` to dev environment
+
+**Type a number or press Enter for suggested action.**
+````
+
+---
+
+## Output (Build Failed)
+
+````markdown
+## Build Failed: {unit-name}
+
+### Error
+```text
+{error message}
+```
+
+### Failure Point
+
+- **Stage**: {compile|test|package}
+- **Exit Code**: {code}
+
+### Logs
+
+{relevant log excerpt}
+
+### Suggested Actions
+
+1. Fix the build error in source code
+2. Re-run build: `build --unit="{unit}"`
+
+### No Artifacts Created
+
+Build must succeed before deployment.
+````
+
+---
+
+## Build Confirmation
+
+**Checkpoint 1**: Ask user to confirm build:
+
+```text
+Ready to build v{version}?
+
+This will:
+1. Verify all tests pass
+2. Create deployable artifact
+3. Tag with version {version}
+4. Push to registry
+
+Proceed with build?
+1 - Yes, build
+2 - Cancel
+```
+
+**Wait for user response.**
+
+---
+
+## Transition
+
+After build approved and completed:
+
+- → **Deploy** - deploy to dev environment
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name, version
+output: Deployable artifact, build.md documentation
+checkpoints: 1
+  - Checkpoint 1: Build approved by user
+```

package/flows/aidlc/skills/operations/deploy.md

@@ -0,0 +1,259 @@
+# Skill: Deploy to Environment
+
+---
+
+## Progress Display
+
+Show at start of this skill (varies by environment):
+
+```text
+### Operations Progress
+- [x] Build approval
+- [ ] Staging deploy  ← current (or)
+- [ ] Production deploy  ← current
+- [ ] Monitoring setup
+```
+
+---
+
+## Checkpoints in This Skill
+
+| Checkpoint | Purpose | Wait For |
+|------------|---------|----------|
+| Checkpoint 2 | Staging deploy approval | User confirmation |
+| Checkpoint 3 | Production deploy approval | User confirmation (⚠️ affects users) |
+
+---
+
+## Goal
+
+Deploy built artifacts to a target environment with progressive validation and rollback capability.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to deploy
+- **Required**: `--env` - Target environment (`dev`, `staging`, `prod`)
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--version` - Specific version (default: latest build)
+
+---
+
+## Process
+
+### 1. Verify Prerequisites
+
+- [ ] **Build exists**: Required for all environments
+- [ ] **Tests passing**: Required for all environments
+- [ ] **Deployed to dev**: Required for staging, prod
+- [ ] **Deployed to staging**: Required for prod
+- [ ] **Staging verification passed**: Required for prod
+
+### 2. Environment Progression
+
+```markdown
+## Deployment Progression
+
+Dev ──────► Staging ──────► Production
+ │            │               │
+ ▼            ▼               ▼
+Fast         Validation      Real users
+iteration    required        approval required
+```
+
+### 3. Pre-Deployment Checks
+
+For the target environment:
+
+- [ ] **Infrastructure**: Verify resources exist
+- [ ] **Secrets**: Confirm secrets configured
+- [ ] **Dependencies**: Check external services available
+- [ ] **Current version**: Record for rollback
+
+### 4. Execute Deployment
+
+Based on deployment type:
+
+- **Container** → Update container image
+- **Serverless** → Deploy function
+- **Static** → Sync to CDN/bucket
+- **Kubernetes** → Apply manifests
+
+### 5. Wait for Health
+
+Monitor deployment until healthy:
+
+- Health check endpoint responding
+- No crash loops
+- Readiness probes passing
+
+### 6. Document Deployment
+
+Append to `deployment/history.md`:
+
+```markdown
+---
+version: {version}
+environment: {env}
+deployed: {timestamp}
+deployed_by: {user}
+status: success
+---
+
+## Deployment: {version} → {env}
+
+### Details
+
+- **Version**: `{version}`
+- **Environment**: {env}
+- **Timestamp**: {timestamp}
+- **Duration**: {duration}
+- **Previous Version**: `{prev-version}`
+
+### Changes
+{diff summary from previous version}
+
+### Rollback Command
+```text
+deploy --unit="{unit}" --env="{env}" --version="{prev-version}"
+```
+
+---
+
+## Output
+
+```markdown
+## Deployment Complete: {unit-name}
+
+### Status
+
+- **Version**: `{version}`
+- **Environment**: {env}
+- **Status**: ✅ Deployed
+- **Health**: ✅ Healthy
+
+### Deployment Details
+- Started: {start-time}
+- Completed: {end-time}
+- Duration: {duration}
+
+### Environment State
+
+- ✅ **Development**: `{version}` - Active
+- ✅ **Staging**: `{version}` - Active
+- ⏳ **Production**: `{prev-version}` - Awaiting
+
+### Documentation Updated
+- `{unit-path}/deployment/history.md`
+
+### Actions
+
+1 - **verify**: Verify this deployment
+2 - **deploy**: Deploy to next environment
+3 - **menu**: Return to operations menu
+
+### Suggested Next Step
+→ **verify** - Verify deployment in {env}
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Output (Production Approval Required)
+
+````markdown
+## Production Deployment: {unit-name}
+
+### ⚠️ PRODUCTION DEPLOYMENT APPROVAL REQUIRED
+
+This deployment will affect real users.
+
+### Pre-Deployment Checklist
+- [x] Staging deployment successful
+- [x] Staging verification passed
+- [x] All tests passing
+- [ ] **Human approval required**
+
+### Deployment Plan
+
+- **Version**: `{version}`
+- **Current Production**: `{current-version}`
+- **Changes**: {summary}
+
+### Rollback Plan
+If issues detected:
+```text
+deploy --unit="{unit}" --env="prod" --version="{current-version}"
+```
+
+### Proceed?
+>
+> "⚠️ This will deploy to PRODUCTION. All staging checks passed. Approve deployment? (yes/no)"
+````
+
+---
+
+## Staging Deploy Confirmation
+
+**Checkpoint 2**: Ask user to confirm staging deploy:
+
+```text
+Ready to deploy to staging?
+
+Version: {version}
+Environment: Staging (production-like validation)
+
+This will update the staging environment.
+1 - Yes, deploy to staging
+2 - Cancel
+```
+
+**Wait for user response.**
+
+---
+
+## Production Deploy Confirmation
+
+**Checkpoint 3**: Ask user to confirm production deploy (⚠️ CRITICAL):
+
+```text
+⚠️ PRODUCTION DEPLOYMENT
+
+This affects real users.
+
+Version: {version}
+Current Production: {current-version}
+All staging tests: ✅ Passed
+
+Rollback command ready:
+  deploy --unit="{unit}" --env="prod" --version="{current-version}"
+
+Proceed with production deployment?
+1 - Yes, deploy to PRODUCTION
+2 - Cancel
+```
+
+**Wait for user response.**
+
+---
+
+## Transition
+
+After deploy approved and completed:
+
+- → **Verify** - verify deployment health
+- → **Monitor** - setup monitoring (after production)
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name, version, environment
+output: Deployed artifact, history.md documentation
+checkpoints: 1-2
+  - Checkpoint 2: Staging deploy approved (if staging)
+  - Checkpoint 3: Production deploy approved (if production)
+```