Fix/aspire devcontainer

.devcontainer/devcontainer.json

@@ -12,10 +12,13 @@
     },
     "ghcr.io/devcontainers/features/docker-in-docker": {
       "moby": false
+    },
+    "ghcr.io/devcontainers/features/dotnet": {
+      "version": "latest"
     }
   },
 
-  "postStartCommand": "copilot plugin marketplace add microsoft/github-copilot-for-azure && copilot plugin install azure@github-copilot-for-azure",
+  "postStartCommand": "copilot plugin install microsoft/github-copilot-for-azure:plugin",
 
   "postCreateCommand": "bash .devcontainer/post-create.sh"
 }

.devcontainer/post-create.sh

@@ -14,10 +14,12 @@ npx playwright install
 curl -sSL https://aspire.dev/install.sh | bash
 
 # Trust HTTPS dev certificates
-dotnet dev-certs https --trust
+# dotnet dev-certs https --trust
 
 # Install TypeScript language server for Copilot CLI LSP support
 npm install -g typescript-language-server
 
 # Install Python docs tooling
 pip install mkdocs mkdocs-material
+
+source /home/node/.bashrc

.github/copilot-instructions.md

@@ -26,7 +26,8 @@ is driven by automated tests generated from those specifications.
 - **Never implement features not in the specs** (specs/frd-*.md)
 - **Never modify tests** without human approval — tests are the contract
 - **Always check Gherkin scenarios** before implementing a feature
-- **Always run tests** after making changes
+- **Never skip tests** — no `test.skip()`, no `xit()`, no `@pending`, no commenting out. Tests are proof that specs are met.
+- **Always run tests** after making changes — the FULL suite, not just "relevant" tests
 - If a spec seems wrong, flag it — do not silently deviate
 
 ## File Organization
@@ -142,6 +143,21 @@ specs/
 - Commit format: `[bugfix] {frd-id}: {description}`
 - Tracked as micro-increments in state.json
 
+
+## Test Discipline Gospel
+Tests are the **proof** that specifications have been implemented correctly. They are not optional, not skippable, and not negotiable.
+
+Key rules:
+- **Tests = proof of spec completion.** A feature without passing tests is not done.
+- **Phase order is sacred.** Tests → Contracts → Implementation → Verify. Never skip or reorder.
+- **All tests must pass before advancing.** No deployment, no commit to main while any test fails.
+- **Regression is mandatory.** After every change, run ALL tests — not just new ones.
+
+### When the User Spots a Problem
+At any point during the flow, if the user identifies something wrong:
+1. **Pause** current work
+2. **Offer** to generate a test that captures the problem
+
 ## Shell-Specific Extensions
 <!-- Shells should add stack-specific instructions below this line -->
 <!-- Examples: language-specific conventions, framework patterns, test commands -->

.github/skills/bug-fix/SKILL.md

@@ -67,7 +67,24 @@ The test must:
 3. Assert the EXPECTED behavior (not the buggy behavior).
 4. Reference the FRD: `// Validates: frd-user-auth.md, AC-3`
 
-### Step 3 — Verify the Test Fails
+### Step 3 — Human Approval of the Test
+
+**MANDATORY GATE.** Present the test to the user for review before proceeding:
+
+1. Show the test code and explain what it verifies.
+2. Explain which FRD acceptance criterion it maps to.
+3. Ask the user to approve or reject the test.
+
+| User Response | Action |
+|--------------|--------|
+| **Approve** | Proceed to Step 4 (verify the test fails). |
+| **Reject with feedback** | Revise the test based on feedback. Re-present. |
+| **Defer** | Log the bug as a known issue in state.json. Resume previous work. |
+
+Do NOT proceed to fix the code until the user approves the test. The test
+defines what "fixed" means — the user must agree on that definition.
+
+### Step 4 — Verify the Test Fails
 
 Run the test and confirm it fails with the expected error:
 
@@ -82,7 +99,7 @@ npx playwright test --grep "duplicate email"
 If the test passes → the bug is not reproduced. Re-examine the reproduction
 steps and the test. Do NOT proceed until the test fails.
 
-### Step 4 — Fix the Code
+### Step 5 — Fix the Code
 
 Apply the minimal change to make the failing test pass:
 
@@ -95,7 +112,7 @@ Apply the minimal change to make the failing test pass:
 The fix should be obvious from the diff. If the fix is complex, it may
 warrant a full increment rather than a bug-fix micro-increment.
 
-### Step 5 — Run Full Regression
+### Step 6 — Run Full Regression
 
 After the fix, run the complete test suite:
 
@@ -113,7 +130,7 @@ npm run build
 Every test must pass — the bug-fix test AND all pre-existing tests. If any
 pre-existing test breaks, the fix is too broad or has side effects. Revise.
 
-### Step 6 — Update State
+### Step 7 — Update State
 
 Update `.spec2cloud/state.json` with the micro-increment:
 
@@ -133,7 +150,7 @@ Update `.spec2cloud/state.json` with the micro-increment:
 }
 ```
 
-### Step 7 — Commit
+### Step 8 — Commit
 
 Commit with the standard bug-fix format:
 
@@ -160,10 +177,11 @@ Every bug fix creates a complete traceability chain:
 Bug Report
   → FRD (frd-{feature}.md, acceptance criterion N)
     → Failing Test (proves the bug exists)
-      → Fix (minimal code change)
-        → Passing Test (proves the bug is fixed)
-          → Commit (links all artifacts)
-            → State (tracked as micro-increment)
+      → Human Approval (user agrees the test captures the problem)
+        → Fix (minimal code change)
+          → Passing Test (proves the bug is fixed)
+            → Commit (links all artifacts)
+              → State (tracked as micro-increment)
 ```
 
 This chain ensures:
@@ -178,6 +196,7 @@ Append to `.spec2cloud/audit.log`:
 
 ```
 [ISO-timestamp] step=bugfix action=test-created bug=bugfix-{nnn} frd={frd-id} test={test-file} result=failing
+[ISO-timestamp] step=bugfix action=test-approved bug=bugfix-{nnn} approver=human result=approved
 [ISO-timestamp] step=bugfix action=fix-applied bug=bugfix-{nnn} files={fixed-files} result=done
 [ISO-timestamp] step=bugfix action=regression-passed bug=bugfix-{nnn} result=all-green
 [ISO-timestamp] step=bugfix action=committed bug=bugfix-{nnn} commit={sha} result=done

AGENTS.md

@@ -171,11 +171,13 @@ Resolve every technology, library, service. Research via MCP tools. Search skill
                                                                    main green + deployed
 ```
 
+> **⚠ MANDATORY:** Every step must execute in order. No step may be skipped, reordered, or compressed. Tests from Step 1 are the proof that specs are met — they are the contract.
+
 #### Step 1: Test Scaffolding
 - **1a** `e2e-generation` — Playwright specs + POMs from flow walkthrough
-- **1b** `gherkin-generation` — Feature files from FRDs (**human gate** after this)
-- **1c** `test-generation` — Cucumber steps + Vitest from Gherkin
-- **1d** Red baseline: new tests fail, existing tests still pass
+- **1b** `gherkin-generation` — Feature files from FRDs (**human gate** after this — user approves scenarios)
+- **1c** `test-generation` — Cucumber steps + Vitest from Gherkin (**human gate** — user approves test code)
+- **1d** Red baseline: new tests fail, existing tests still pass. Zero `test.skip()` allowed.
 **Commit:** `[increment] {id}/tests — test scaffolding complete`
 
 #### Step 2: Contracts → `contract-generation` skill

apphost.cs

@@ -1,12 +1,13 @@
-#:sdk Aspire.AppHost.Sdk@13.1.0
-#:package Aspire.Hosting.JavaScript@13.1.0
-#:package Aspire.Hosting.Python@13.1.0
+#:sdk Aspire.AppHost.Sdk@13.2.0
+#:package Aspire.Hosting.JavaScript@13.2.0
+#:package Aspire.Hosting.Python@13.2.0
 
 var builder = DistributedApplication.CreateBuilder(args);
 
 // API — Express.js / TypeScript backend
 var api = builder.AddJavaScriptApp("api", "./src/api")
     .WithEnvironment("JWT_SECRET", "aspire-local-dev-jwt-secret")
+    .WithHttpEndpoint(port: 5001, env: "PORT")
     .WithHttpHealthCheck("/health");
 
 // Web — Next.js frontend

aspire.config.json

@@ -0,0 +1,5 @@
+{
+  "appHost": {
+    "path": "apphost.cs"
+  }
+}

docs/quickstart.md

@@ -1,51 +1,143 @@
 # Quick Start
 
-Get spec2cloud running in your project in under 5 minutes.
+Get the spec2cloud TypeScript shell running in under 5 minutes.
 
 ## Prerequisites
 
-- GitHub Copilot (Chat enabled) or Claude Code
-- VS Code with Copilot extension
-- Azure CLI + Azure Developer CLI (azd)
-- Node.js 20+ or .NET 8+
+### Option A: Use Codespaces / DevContainer (Recommended)
 
-## Option 1: npx (Recommended)
+All spec2cloud shells include a fully configured **DevContainer** / **GitHub Codespaces** setup. Everything is pre- the only thing you need locally is:installed 
+
+- **Docker Desktop** (or any Docker-compatible  [docker.com](https://www.docker.com/products/docker-desktop/)runtime) 
+- **VS Code** with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+Then simply open the repo in VS Code and click "Reopen in Container", or launch a GitHub Codespace from the repo page. All prerequisites below are handled automatically.
+
+### Option B: Local Setup
+
+If you prefer running locally without containers, install the following:
+
+#### Core Tools (all shells need these)
+
+| Tool | Purpose | Install |
+|------|---------|---------|
+| **GitHub Copilot** | AI orchestrator | [github.com/features/copilot](https://github.com/features/copilot) |
+| **VS Code** | Editor with Copilot extension | [code.visualstudio.com](https://code.visualstudio.com/) |
+| **Azure CLI** | Azure resource management | [aka.ms/installcli](https://aka.ms/installcli) |
+| **Azure Developer CLI (azd)** | Deploy to Azure | [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) |
+| **.NET SDK (latest)** | Required for Aspire orchestration | [dot.net](https://dot.net/download) |
+| **.NET Aspire** | Local service orchestration | `curl -sSL https://aspire.dev/install.sh \| bash` |
+| **Docker** | Container builds & deployment | [docker.com](https://www.docker.com/products/docker-desktop/) |
+| **Git** | Source control | [git-scm.com](https://git-scm.com/) |
+
+#### Language-Specific (TypeScript)
+
+- **Node.js 20+** and ** [nodejs.org](https://nodejs.org/)npm** 
+
+#### Optional (Recommended)
+
+- ** `npx playwright install` (for E2E tests)Playwright** 
+- ** `pip install mkdocs mkdocs-material` (for documentation site)MkDocs** 
+
+### Install Scripts
+
+<details>
+<summary><strong>macOS (Homebrew)</strong></summary>
 
 ```bash
-npx spec2cloud init
+# Core tools
+brew install azure-cli
+brew install azd
+brew install --cask docker
+brew install dotnet
+curl -sSL https://aspire.dev/install.sh | bash
+
+# Language-specific
+brew install node@20
+
+# Optional
+npx playwright install-deps && npx playwright install
+pip install mkdocs mkdocs-material
 ```
 
-## Option 2: One-Line Install
+</details>
+
+<details>
+<summary><strong>Linux (Ubuntu/Debian)</strong></summary>
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/EmeaAppGbb/spec2cloud/vNext/scripts/quick-install.sh | bash
+# Core tools
+curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
+curl -fsSL https://aka.ms/install-azd.sh | bash
+wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh && chmod +x dotnet-install.sh && ./dotnet-install.sh
+curl -sSL https://aspire.dev/install.sh | bash
+
+# Language-specific
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Optional
+npx playwright install-deps && npx playwright install
+pip install mkdocs mkdocs-material
 ```
 
-## Option 3: Shell Template (Recommended for New Projects)
+</details>
 
-Use a pre-configured shell:
+<details>
+<summary><strong>Windows (winget / PowerShell)</strong></summary>
 
-- **Next.js + TypeScript**: `shell-typescript`
-- **.NET**: `shell-dotnet`
-- **Agentic .NET**: `agentic-shell-dotnet`
-- **Agentic Python**: `agentic-shell-python`
+```powershell
+# Core tools
+winget install Microsoft.AzureCLI
+winget install Microsoft.Azd
+winget install Microsoft.DotNet.SDK.Preview
+winget install Docker.DockerDesktop
+dotnet workload install aspire
 
-## Option 4: Add to Existing Project
+# Language-specific
+winget install OpenJS.NodeJS.LTS
+
+# Optional
+npx playwright install
+pip install mkdocs mkdocs-material
+```
+
+</details>
+
+### Verify Installation
 
 ```bash
-npx spec2cloud init --minimal
+# Core
+az --version && azd version && dotnet --version && aspire --version && docker --version
+
+# Language
+node --version  # v20+
+npm --version
 ```
 
-## Your First Workflow
+---
+
+## Getting Started
+
+### 1. Clone and Run
+
+```bash
+git clone https://github.com/EmeaAppGbb/spec2cloud-shell-nextjs-typescript.git
+cd spec2cloud-shell-nextjs-typescript
+dotnet run --project apphost.cs    # Aspire starts all services
+```
+
+### 2. Open in VS Code with Copilot
+
+The orchestrator (AGENTS.md) activates automatically when you start a Copilot conversation.
+
+### 3. Start Building
 
-1. Open your project in VS Code with GitHub Copilot
-2. Start a conversation with Copilot — the orchestrator (AGENTS.md) activates automatically
-3. Describe your app idea or ask Copilot to analyze your existing codebase
-4. At each human gate, review and approve
-5. Watch as tests, contracts, implementation, and deployment happen automatically
+ deploy
+- **Brownfield:** Ask Copilot to analyze the existing  it extracts specs, then you choose pathscodebase 
 
 ## What Happens Next
 
-**Greenfield:** Phase 1 Discovery (spec → UI → plan → tech stack) → Phase 2 Delivery (tests → contracts → code → deploy) × N increments
+ deploy)  N increments
 
-**Brownfield:** Phase B1 Extract → Phase B2 Spec-Enable → Testability Gate (can you test it?) → Track A (green baseline tests) or Track B (behavioral docs) → Choose paths → Assess → Plan → Phase 2 Delivery
+ Phase 2 Delivery