Implementation Plan: aws-sandbox npm Package Release v0.3.18

Status: APPROVED Created: 2026-02-02 Updated: 2026-02-02 (RQ1+RQ2 Upgrades Applied) Spec Reference: specs/aws-sandbox/spec.md ADLC Phase: 1.2 (Technical Feasibility Assessment)

0. Sprint Planning (RQ1 Upgrade)

0.1 Sprint Planning Checklist

Phase	Task	Owner	Status
Preparation	Review previous sprint retrospective	product-owner	✅
Preparation	Groom backlog (INVEST validation)	product-owner	✅
Preparation	Estimate capacity	cloud-architect	✅
Meeting	Review sprint goal	HITL Manager	⏳ Pending
Meeting	Commit to sprint backlog	Team	⏳ Pending
Meeting	Assign tasks	product-owner	✅
Follow-up	Update velocity tracking	qa-engineer	⏳ Pending
Follow-up	Publish sprint plan	HITL Manager	⏳ Pending

0.2 Sprint Team Members

Name	Role	Capacity (hours/sprint)	Allocation
@nnthanh101	HITL Manager	40h	25% oversight
product-owner	Business Validation Agent	∞	100%
cloud-architect	Technical Design Agent	∞	100%
infrastructure-engineer	Execution Agent	∞	100%
qa-engineer	Test Orchestration Agent	∞	100%

0.3 Sprint Details

Field	Value
Sprint Theme	aws-sandbox v0.3.18 npm Release with Phase 3.5 Consumer E2E
Start Date	2026-02-01
End Date	2026-02-02
Sprint Duration	2 days
Story Points Committed	21

0.4 Velocity Tracking

Sprint	Committed	Completed	Velocity	Notes
Sprint 0.3.17	18	15	83%	Phase 3.5 not executed
Sprint 0.3.18	21	TBD	TBD	Current sprint
3-Sprint Avg	19.5	15	77%	Baseline velocity

0.5 Capacity Planning

Team Member	Available Hours	Meetings/Overhead	Net Capacity
HITL Manager	40h	10h	30h (75%)
AI Agents	∞	0h	∞
Total	40h	10h	30h + agents

0.6 Previous Sprint Summary (v0.3.17)

Item	Value
Theme	Tier 1+2 Testing Stabilization
Story Points	15/18 (83%)
Key Achievement	29/29 Tier 1, 11/11 Tier 2 PASS
Carryover	Phase 3.5 Consumer E2E (not executed)
Retrospective Action	Add Phase 3.5 as BLOCKING gate

1. Plan Overview

1.1 Objective

Execute ADLC 6+1 phase lifecycle for aws-sandbox npm package release v0.3.18 with Phase 3.5 Consumer E2E as the primary quality gate.

1.2 Timeline

Phase	Duration	Status
Phase 1: PLAN	2026-02-01	65% → 100%
Phase 2: BUILD	2026-02-02	75% → 100%
Phase 3: TEST/RELEASE	2026-02-02	53% → 100%
Phase 4-6: DEPLOY/MONITOR/OPERATE	Post-release	Pending

1.3 Critical Path

BLOCK-000 (Phase 1) → BLOCK-001 (Phase 2) → BLOCK-002 (Phase 3.5) → npm publish

2. Technical Design

2.1 Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     aws-sandbox npm Package                      │
├─────────────────────────────────────────────────────────────────┤
│  bin/cli.js              → CLI entrypoint (aws-sandbox command) │
│  lib/*.js                → Compiled TypeScript (CDK constructs) │
│  source/infrastructure/  → Pre-bundled app.cjs (~58MB)          │
│  source/lambdas-bundled/ → Lambda ZIP files                     │
│  source/frontend/dist/   → React frontend build                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Consumer Environment                          │
├─────────────────────────────────────────────────────────────────┤
│  npm install [email protected]                                 │
│  npx aws-sandbox --version                                      │
│  npx aws-sandbox synth --all                                    │
│  npx aws-sandbox deploy --localstack                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    LocalStack (Tier 2)                          │
├─────────────────────────────────────────────────────────────────┤
│  CloudFormation    → Stack deployment                           │
│  DynamoDB          → LeaseTable, SandboxAccountTable            │
│  S3                → Artifact storage                           │
│  Lambda            → Account provisioning functions             │
│  API Gateway       → REST API endpoints                         │
└─────────────────────────────────────────────────────────────────┘

2.2 Component Dependencies

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Phase 1    │────▶│   Phase 2    │────▶│   Phase 3    │
│    PLAN      │     │    BUILD     │     │    TEST      │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │                    │
       ▼                    ▼                    ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  spec.md     │     │  app.cjs     │     │  Phase 3.5   │
│  plan.md     │     │  (build)     │     │  Consumer    │
│  tasks.md    │     │              │     │  E2E Deploy  │
└──────────────┘     └──────────────┘     └──────────────┘

2.3 AWS Well-Architected Framework Alignment (RQ2 Upgrade)

Pillar	Coverage	Implementation	Gap
Operational Excellence	75%	Runbook via tasks.md, IaC via CDK, PDCA cycles	Automated rollback
Security	80%	Apache-2.0 license, no secrets in package, npm audit	Threat model (deferred)
Reliability	90%	RTO 15min, RPO 0min, Phase 3.5 validation, rollback procedures	Multi-region (N/A for npm)
Performance Efficiency	70%	Tier 1 ≤10s, Tier 2 ≤60s, Consumer deploy ≤5min	Lambda cold start optimization
Cost Optimization	85%	$0 Tier 1+2 on LocalStack, ~$50/mo Tier 3 deferred	FinOps tagging (deferred)
Sustainability	50%	Local-first testing reduces cloud compute	Carbon footprint tracking

Overall Well-Architected Score: 75% (target: ≥70% for npm package)

2.4 Architecture Diagram References (RQ4 Upgrade)

2.4.1 Draw.io Diagrams (SVG)

Diagram	C4 Level	Purpose	Path
High-Level	L1 Context	System boundaries, external actors	`cdk/docs/diagrams/architecture/high-level.drawio.svg`
In-Depth	L2 Container	CDK stacks, AWS services	`cdk/docs/diagrams/architecture/in-depth.drawio.svg`
Stack Dependencies	L2 Container	Inter-stack relationships	`cdk/docs/diagrams/architecture/stack-dependencies.drawio.svg`
Stack Relationships	L2 Container	Data flow between stacks	`cdk/docs/diagrams/architecture/stack-relationships.drawio.svg`
Software Layers	L3 Component	Application architecture	`cdk/docs/diagrams/architecture/software-architecture-layers.drawio.svg`
Account Cleaner	L3 Component	Cleanup workflow	`cdk/docs/diagrams/architecture/account-cleaner.drawio.svg`
Event Infrastructure	L3 Component	EventBridge patterns	`cdk/docs/diagrams/architecture/event-infrastructure.drawio.svg`
Organizational Units	L2 Container	AWS Organizations	`cdk/docs/diagrams/architecture/organizational-units.drawio.svg`
Web App	L3 Component	Frontend architecture	`cdk/docs/diagrams/architecture/web-app.drawio.svg`

2.4.2 Mermaid Diagrams (Docusaurus-Ready)

Diagram	Type	Purpose	Path
AWS 4-Stack Architecture	architecture-beta	Hub/IDC account stacks	`cdk/docs/ARCHITECTURE-DIAGRAMS.md#1`
Consumer E2E Flow	flowchart	5-layer Phase 3.5 validation	`cdk/docs/ARCHITECTURE-DIAGRAMS.md#2`
3-Tier Testing Pipeline	flowchart	Tier 1 → 2 → 3.5 → 3 flow	`cdk/docs/ARCHITECTURE-DIAGRAMS.md#3`
Deployment Sequence	flowchart	Phase-based deployment order	`cdk/docs/ARCHITECTURE-DIAGRAMS.md#4`
npm Package Structure	flowchart	Tarball → consumer CLI flow	`cdk/docs/ARCHITECTURE-DIAGRAMS.md#5`
ADLC 6+1 Lifecycle	flowchart	Full release workflow	`cdk/docs/ARCHITECTURE-DIAGRAMS.md#6`
Stack Resources	flowchart	DataStack + ComputeStack detail	`cdk/docs/ARCHITECTURE-DIAGRAMS.md#7`

3. Implementation Phases

3.1 Phase 1: PLAN (Complete SPECKIT Deliverables)

3.1.1 Create spec.md (✅ DONE)

# Created: specs/aws-sandbox/spec.md
# Evidence: This file exists

3.1.2 Create plan.md (✅ IN PROGRESS)

# Creating: specs/aws-sandbox/plan.md
# Evidence: This file

3.1.3 Create tasks.md

# Creating: specs/aws-sandbox/tasks.md
# Evidence: Task breakdown with dependencies

3.1.4 HITL Approval

# Create: tmp/cdk/approvals/hitl-approval-2026-02-02.md
# Action: Manager signs off on Phase 1 deliverables

3.2 Phase 2: BUILD (app.cjs Generation)

3.2.1 Build Consumer App

cd /Volumes/Working/projects/sandbox/cdk
npm run build:consumer-app

# Expected output:
# source/infrastructure/dist/infrastructure/bin/app.cjs (~58MB)

# Validation:
ls -la source/infrastructure/dist/infrastructure/bin/app.cjs

3.2.2 Build All Workspaces

npm run build

# Validates:
# - TypeScript compilation
# - Lambda bundling
# - Frontend build

3.3 Phase 3: TEST/RELEASE

3.3.1 Tier 1 Snapshot Tests (✅ PASS)

npm run test:snapshot
# Result: 29/29 PASS (5.38s)
# Evidence: tmp/cdk/test-results/tier1-2026-02-01-081221.log

3.3.2 Tier 2 LocalStack Tests (✅ PASS)

npm run test:localstack
# Result: 11/11 PASS (1.28s)
# Evidence: tmp/cdk/test-results/tier2-2026-02-01-081151.log

3.3.3 Phase 3.5 Consumer E2E Deploy (CRITICAL)

Layer 1: Package Installation

# Create tarball
npm pack
# Expected: aws-sandbox-0.3.18.tgz

# Create isolated environment
mkdir -p tmp/cdk/consumer-test
cd tmp/cdk/consumer-test
npm init -y
npm install ../../../aws-sandbox-0.3.18.tgz

# Validate critical files
ls node_modules/aws-sandbox/bin/cli.js
ls node_modules/aws-sandbox/lib/index.js
ls node_modules/aws-sandbox/source/infrastructure/dist/infrastructure/bin/app.cjs

Layer 2: CLI Availability

npx aws-sandbox --version
# Expected: 0.3.18

Layer 3: Consumer Mode Detection

# Consumer mode should be auto-detected (no source/infrastructure/bin/app.ts)
npx aws-sandbox synth --all 2>&1 | head -20

Layer 4: LocalStack Deployment

# Ensure LocalStack is running
docker compose -f /Volumes/Working/projects/sandbox/cdk/docker-compose.yml up -d localstack

# Wait for health
until curl -sf http://localhost:4566/_localstack/health; do sleep 2; done

# Deploy to LocalStack
AWS_ENDPOINT_URL=http://localhost:4566 npx aws-sandbox deploy --localstack --require-approval never

# Validate stacks
aws --endpoint-url=http://localhost:4566 cloudformation list-stacks --stack-status-filter CREATE_COMPLETE

Layer 5: Evidence Capture

# Capture deployment logs
mkdir -p /Volumes/Working/projects/sandbox/tmp/cdk/release-logs
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
# Evidence file: tmp/cdk/release-logs/phase3.5-consumer-${TIMESTAMP}.log

3.3.4 npm Publish (HITL Required)

# Only after Phase 3.5 PASS
# Requires HITL approval

# Pre-publish checklist:
# - [ ] Phase 3.5 PASS evidence
# - [ ] Version 0.3.18 in package.json
# - [ ] CHANGELOG updated
# - [ ] HITL approval signature

# npm publish --access public

4. Testing Strategy

4.1 3-Tier Testing Matrix

Tier	Type	Duration	Cost	Coverage	Status
1	Snapshot	5.38s	$0	70-80%	✅ PASS
2	LocalStack	1.28s	$0	+15-20%	✅ PASS
3	AWS E2E	5-10min	~$50/mo	+5-10%	Deferred

4.2 Phase 3.5 Validation Criteria

Layer	Check	Pass Criteria
1	Package install	npm install succeeds
2	CLI availability	--version returns 0.3.18
3	Mode detection	Consumer mode active
4	Synth	CloudFormation templates generated
5	Deploy	CREATE_COMPLETE status

4.3 SLO Targets (RQ2 Upgrade)

SLO	Target	Measurement Method	Alert Threshold
Availability	99.9%	npm registry uptime	N/A (external)
Tier 1 Latency	≤10s	`npm run test:snapshot` duration	>15s
Tier 2 Latency	≤60s	`npm run test:localstack` duration	>90s
Phase 3.5 Latency	≤5min	Consumer E2E total duration	>10min
Consumer Install	100%	npm install success rate	Any failure = BLOCK
CLI Availability	100%	`npx aws-sandbox --version` success	Any failure = BLOCK
Deploy Success	100%	CloudFormation CREATE_COMPLETE	Any failure = BLOCK
Error Rate	0%	Errors in Phase 3.5 evidence log	Any error = BLOCK

SLO Burn Rate: Phase 3.5 failures must be ≤0 for npm publish approval

4.4 Progressive Rollout Strategy (RQ2 Upgrade)

Stage	Audience	Validation	Rollback Trigger
1. npm pack	Internal only	Phase 3.5 Consumer E2E	Any layer failure
2. npm publish --tag beta	Early adopters	Download + install monitoring	>5% failure rate
3. npm publish --tag latest	All users	npm download stats	Critical bug report

Canary Deployment: Not applicable for npm packages (instant global publish)

5. Risk Mitigation

5.1 Phase 3.5 Failure Recovery

IF Phase 3.5 fails:
Capture error logs to tmp/cdk/release-logs/
Identify failure layer (1-5)
Fix issue in source
Rebuild (npm run build:consumer-app)
Re-execute Phase 3.5
DO NOT proceed to npm publish until PASS

5.2 Rollback Procedures

Scenario	RTO	RPO	Action
Build failure	0min	0min	Fix and rebuild
Phase 3.5 failure	15min	0min	Fix and re-test
Post-publish bug	2-3h	0min	npm deprecate + hotfix

6. Evidence Requirements

6.1 Required Artifacts

Artifact	Path	Status
spec.md	specs/aws-sandbox/spec.md	✅ Created
plan.md	specs/aws-sandbox/plan.md	✅ Creating
tasks.md	specs/aws-sandbox/tasks.md	Pending
HITL approval	tmp/cdk/approvals/hitl-approval-2026-02-02.md	Pending
Phase 3.5 evidence	tmp/cdk/release-logs/phase3.5-consumer-*.log	Pending

6.2 Validation Summary

{
  "phase1_complete": false,
  "phase2_complete": false,
  "phase3_5_pass": false,
  "hitl_approved": false,
  "ready_for_publish": false
}

7. Claude Code Components

7.1 Agents to Invoke

Agent	Purpose	Phase
product-owner	Business validation	1
cloud-architect	Technical design	1
infrastructure-engineer	Build/Deploy	2, 3
qa-engineer	Test execution	3

7.2 Commands to Execute

Command	Purpose	Phase
/speckit.specify	Create spec.md	1
/speckit.plan	Create plan.md	1
/speckit.tasks	Create tasks.md	1
/cdk:test	Run Tier 1+2	3
/cdk:release	Full release workflow	3

7.3 Skills Loaded

testing-cdk-infrastructure.md - 3-tier testing
releasing-npm-package.md - 7-phase release
operational-excellence.md - PDCA cycles

8. Approval Gates

8.1 Phase 1 Gate (HITL Required)

spec.md reviewed and approved
plan.md reviewed and approved
tasks.md reviewed and approved
Manager signature in tmp/cdk/approvals/

8.2 Phase 3.5 Gate (Automated)

Layer 1: Package installation SUCCESS
Layer 2: CLI availability SUCCESS
Layer 3: Consumer mode detected
Layer 4: Synth SUCCESS
Layer 5: Deploy CREATE_COMPLETE

8.3 npm Publish Gate (HITL Required)

Phase 3.5 evidence reviewed
Version confirmed (0.3.18)
CHANGELOG reviewed
Manager approval for publish

9. Next Steps

Immediate: Complete tasks.md creation
Short-term: Build app.cjs (npm run build:consumer-app)
Critical: Execute Phase 3.5 Consumer E2E Deploy
Final: Request HITL approval for npm publish

Plan Version: 1.1.0 ADLC Phase: 1.2 (Technical Feasibility Assessment) Updated: 2026-02-02 (RQ1+RQ2 Upgrades: Sprint Planning, Well-Architected, SLOs, Architecture Refs) Next Action: Execute Phase 3.5 Consumer E2E Deploy

0. Sprint Planning (RQ1 Upgrade)​

0.1 Sprint Planning Checklist​

0.2 Sprint Team Members​

0.3 Sprint Details​

0.4 Velocity Tracking​

0.5 Capacity Planning​

0.6 Previous Sprint Summary (v0.3.17)​

1. Plan Overview​

1.1 Objective​

1.2 Timeline​

1.3 Critical Path​

2. Technical Design​

2.1 Architecture Overview​

2.2 Component Dependencies​

2.3 AWS Well-Architected Framework Alignment (RQ2 Upgrade)​

2.4 Architecture Diagram References (RQ4 Upgrade)​

2.4.1 Draw.io Diagrams (SVG)​

2.4.2 Mermaid Diagrams (Docusaurus-Ready)​

3. Implementation Phases​

3.1 Phase 1: PLAN (Complete SPECKIT Deliverables)​

3.1.1 Create spec.md (✅ DONE)​

3.1.2 Create plan.md (✅ IN PROGRESS)​

3.1.3 Create tasks.md​

3.1.4 HITL Approval​

3.2 Phase 2: BUILD (app.cjs Generation)​

3.2.1 Build Consumer App​

3.2.2 Build All Workspaces​

3.3 Phase 3: TEST/RELEASE​

3.3.1 Tier 1 Snapshot Tests (✅ PASS)​

3.3.2 Tier 2 LocalStack Tests (✅ PASS)​

3.3.3 Phase 3.5 Consumer E2E Deploy (CRITICAL)​

3.3.4 npm Publish (HITL Required)​

4. Testing Strategy​

4.1 3-Tier Testing Matrix​

4.2 Phase 3.5 Validation Criteria​

4.3 SLO Targets (RQ2 Upgrade)​

4.4 Progressive Rollout Strategy (RQ2 Upgrade)​

5. Risk Mitigation​

5.1 Phase 3.5 Failure Recovery​

5.2 Rollback Procedures​

6. Evidence Requirements​

6.1 Required Artifacts​

6.2 Validation Summary​

7. Claude Code Components​

7.1 Agents to Invoke​

7.2 Commands to Execute​

7.3 Skills Loaded​

8. Approval Gates​

8.1 Phase 1 Gate (HITL Required)​

8.2 Phase 3.5 Gate (Automated)​

8.3 npm Publish Gate (HITL Required)​

9. Next Steps​