chore: enhance agent charters with codebase-specific patterns

- TypeScriptDev: fix inaccurate tsconfig claims, add ESM/singleton/HttpError patterns
- TestEngineer: add vi.mock/vi.spyOn, IApimClient mocking, os.tmpdir cleanup
- NodeJsDev: add exit code constants, dual-mode init, template directories
- ApimExpert: add source file refs, HttpError, noRetryOn5xx, WSDL fallback
- AzdoExpert: add template source references, apiops init integration
- GitHubExpert: add workflow files, OIDC pattern, template references
- ApiOpsLead: add architectural review checklist, key file paths
- Fix 10 stale .specify/memory/ paths to .squad/identity/constitution.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Peter Hauge

.squad/agents/apicexpert/history.md

@@ -4,7 +4,7 @@
 
 - **Project:** apiops-cli — TypeScript CLI for Azure API Management and API Center
 - **Spec:** `specs/001-apiops-cli/spec.md`
-- **Constitution:** `.specify/memory/constitution.md` (v2.1.0)
+- **Constitution:** `.squad/identity/constitution.md` (v2.1.0)
 - **User:** Elizabeth Maher
 - **Stack:** TypeScript 5.x, Node.js 22 LTS, `@azure/identity` for auth, raw APIC REST API (no SDK for payloads)
 - **APIC REST API base:** `https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ApiCenter/services/{svc}`

.squad/agents/apimexpert/charter.md

@@ -29,6 +29,54 @@
 - I preserve unknown properties. Silent data loss is prohibited (Constitution §VII).
 - Token refresh is the credential chain's job. I depend on `@azure/identity` token lifecycle, not manual refresh logic.
 
+### Codebase Patterns
+
+These are the concrete patterns and file paths I work with in this project.
+
+#### Key Source Files
+| File | Purpose |
+|------|---------|
+| `src/clients/iapim-client.ts` | `IApimClient` interface — `listResources`, `getResource`, `putResource`, `deleteResource`, `listApiRevisions`, `getApiSpecification`, `validatePreFlight` |
+| `src/clients/apim-client.ts` | `ApimClient` concrete implementation + `HttpError` class |
+| `src/clients/iartifact-store.ts` | `IArtifactStore` interface — the other side of extract/publish |
+| `src/lib/resource-uri.ts` | `buildArmUri()`, `parseArmUri()` — ARM URI construction and parsing |
+| `src/lib/resource-path.ts` | `deriveListPaths()`, `buildResourceLabel()` — artifact path mapping and log labels |
+| `src/services/extract-service.ts` | Extract orchestration using `IApimClient` + `IArtifactStore` |
+| `src/services/publish-service.ts` | Publish orchestration with dependency ordering |
+
+#### HttpError Pattern
+- `HttpError` extends `Error` with `status: number` and `code: string` fields
+- Callers branch on `error.status` (e.g., 404 → optional resource, 409 → conflict), never on `error.message`
+- `allowedNonOkStatuses` parameter lets callers declare expected non-2xx codes without triggering error handling
+
+#### Retry & Failure Patterns
+- Exponential backoff with jitter for transient failures
+- HTTP 429: respect `Retry-After` header, do not retry immediately
+- `noRetryOn5xx: true` for deterministic failures — APIM's WSDL/WADL export 500 errors are permanent, not transient (decision: 2026-04-21)
+- `allowedNonOkStatuses` for caller-handled error codes (e.g., 404 on optional resources)
+
+#### Token Caching
+- 5-minute buffer before token expiry
+- Promise-based deduplication to prevent concurrent refresh — if a refresh is in-flight, subsequent callers await the same promise
+
+#### SOAP/WADL Spec Extraction (Decision: 2026-04-21)
+- `getApiSpecification` requests `format=wsdl-link` first
+- On HTTP 5xx, falls back to inline `format=wsdl` (returns raw WSDL XML in `properties.value`)
+- WADL follows the same pattern: `wadl-link` → `wadl` fallback
+- Inline format IS re-importable via PUT `?import=true&format=wsdl` — contrary to Azure/apiops reference tool's claim
+- XML fallback bypasses 5xx retry (`noRetryOn5xx=true`) because the 500 is deterministic (decision: 2026-04-21)
+
+#### Synthetic GraphQL Detection (Decision: 2026-04-21)
+- Before calling `graphql-link` export, probe ApiSchema children via `hasGraphQLSchemaResource`
+- If synthetic GraphQL (SDL stored as ApiSchema child): skip export, schema is captured by standard ApiSchema extraction
+- If pass-through GraphQL: call `graphql-link` normally
+- APIM returns HTTP 406 on `graphql-link` for synthetic APIs — skipping avoids the error
+
+#### ARM URI Construction
+- `buildArmUri()` constructs fully qualified ARM resource URIs
+- `deriveListPaths()` generates list operation paths for resource enumeration
+- `buildResourceLabel()` generates human-readable hierarchical paths for log output (e.g., `apim-1/petstore/get-user`)
+
 ## Boundaries
 
 **I handle:** APIM REST API calls, resource model knowledge, dependency graph, pagination, retry, revision ordering, workspace scoping, secret placeholder replacement.
@@ -49,7 +97,11 @@
 
 Before starting work, run `git rev-parse --show-toplevel` to find the repo root, or use the `TEAM ROOT` provided in the spawn prompt. All `.squad/` paths must be resolved relative to this root.
 
-Before starting work, read `.squad/decisions.md` for team decisions that affect me.
+Before starting work, read `.squad/identity/constitution.md` and `.squad/decisions.md` for team decisions that affect me. Key decisions I own:
+- **SOAP/WADL spec extraction** (2026-04-21): wsdl-link first, inline XML fallback on 5xx
+- **Synthetic GraphQL skip** (2026-04-21): probe ApiSchema before graphql-link export
+- **XML export bypass retry** (2026-04-21): `noRetryOn5xx=true` for deterministic WSDL/WADL failures
+- **Text-first XML parsing** (2026-04-10): `getResource` reads as text, detects XML, wraps in ARM envelope
 After making a decision others should know, write it to `.squad/decisions/inbox/apimexpert-{brief-slug}.md` — the Scribe will merge it.
 
 ## Voice

.squad/agents/apimexpert/history.md

@@ -4,7 +4,7 @@
 
 - **Project:** apiops-cli — TypeScript CLI for Azure API Management (`apiops extract`, `apiops publish`, `apiops init`)
 - **Spec:** `specs/001-apiops-cli/spec.md`
-- **Constitution:** `.specify/memory/constitution.md` (v2.1.0)
+- **Constitution:** `.squad/identity/constitution.md` (v2.1.0)
 - **User:** Elizabeth Maher
 - **Stack:** TypeScript 5.x, Node.js 22 LTS, `@azure/identity` for auth, raw APIM REST API (no SDK for payloads)
 - **APIM REST API base:** `https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{svc}`

.squad/agents/apiopslead/charter.md

@@ -20,11 +20,45 @@
 
 ## How I Work
 
-- Before approving any design: I check it against the constitution at `.specify/memory/constitution.md`
+- Before approving any design: I check it against the constitution at `.squad/identity/constitution.md`
 - I decompose complex features into independently testable units — if it can't be tested without live Azure, the design is wrong
 - I surface trade-offs explicitly. I don't bury them in implementation details.
 - Complexity must be justified in writing (plan.md or PR description) before I accept it — per Constitution §V
 
+### What I Check
+
+Architectural review protocol — I check these on every design proposal and PR.
+
+#### Structural Integrity
+- Service-layer code depends on `IApimClient` / `IArtifactStore` interfaces, never concrete implementations (§VI)
+- New modules follow existing patterns: singleton + class export, `HttpError` for error typing, `Record<string, unknown>` for payloads
+- File placement matches the established structure: clients in `src/clients/`, services in `src/services/`, utilities in `src/lib/`
+
+#### Constitution Alignment
+- **§I CLI-First:** New commands have non-interactive flag equivalents, `--format json` support, distinct exit codes
+- **§IV Idempotent:** Write operations have `--dry-run`, destructive ops require explicit flags
+- **§V YAGNI:** No speculative features — complexity justified in writing
+- **§VI Testability:** Dependencies injectable, no sealed coupling, test file exists for new source
+- **§VII Forward Compat:** Payloads are `Record<string, unknown>`, unknown properties preserved
+- **§VIII Secret Safety:** No credentials in output, `REDACTION_MARKER` for secrets, bearer redaction
+
+#### Key Decisions I Enforce (from decisions.md)
+- Dual-mode package consumption — public npm vs local tarball (2026-04-29)
+- SOAP/WADL spec extraction with link format + XML fallback (2026-04-21)
+- `noRetryOn5xx` for deterministic APIM failures (2026-04-21)
+- Text-first XML parsing in `getResource` (2026-04-10)
+- `--log-level` replaces `--verbose` (2026-04-13)
+
+#### Key File Paths I Reference
+| File | Why I Care |
+|------|-----------|
+| `specs/001-apiops-cli/spec.md` | Every feature must trace to a spec requirement |
+| `src/clients/iapim-client.ts` | The core APIM abstraction — changes need architectural review |
+| `src/clients/iartifact-store.ts` | The core artifact abstraction — changes need architectural review |
+| `src/models/types.ts` | Core type definitions — changes ripple across the codebase |
+| `src/lib/exit-codes.ts` | Exit code contract — changes break CI/CD pipelines |
+| `.squad/identity/constitution.md` | Supreme governance document |
+
 ## Boundaries
 
 **I handle:** Architecture proposals, code review, scope decisions, triage, escalations, cross-agent blockers.
@@ -45,7 +79,7 @@
 
 Before starting work, run `git rev-parse --show-toplevel` to find the repo root, or use the `TEAM ROOT` provided in the spawn prompt. All `.squad/` paths must be resolved relative to this root.
 
-Before starting work, read `.squad/decisions.md` for team decisions that affect me.
+Before starting work, read `.squad/identity/constitution.md` and `.squad/decisions.md` for team decisions that affect me.
 After making a decision others should know, write it to `.squad/decisions/inbox/apiopslead-{brief-slug}.md` — the Scribe will merge it.
 If I need another team member's input, say so — the coordinator will bring them in.
 

.squad/agents/apiopslead/history.md

@@ -123,4 +123,36 @@
 
 **Key insight:** A generic "enforce TypeScript strict mode" instruction is useless if the reviewer doesn't know the specific patterns to look for. Project-specific checklists with severity annotations turn a reviewer from "looks fine to me" into a systematic quality gate.
 
+### 2026-05-01: Charter Enhancement Priority Analysis
+
+**What:** Analyzed all 8 non-CodeReviewer charters to identify inaccuracies, generic content, and missing codebase-specific patterns. Produced a prioritized recommendation table for charter improvements modeled on the CodeReviewer enhancement.
+
+**Key findings:**
+1. **TypeScriptDev** has an outright inaccuracy: claims `noUncheckedIndexedAccess` in tsconfig.json — it's not there. Also lists target as "ESNext" when actual target is ES2022.
+2. **TestEngineer** is the most generic — could apply to any Vitest project. Missing all project-specific mocking patterns, test structure conventions, and coverage thresholds.
+3. **NodeJsDev** lacks reference to actual exit code constants (`EXIT_SUCCESS/PARTIAL/FATAL`) and the real `init-service.ts` implementation patterns.
+4. **ApimExpert** and **AzdoExpert/GitHubExpert** are moderately generic but less impactful since they're advisory roles that consult docs.
+5. **OpenSourceExpert** and **ApicExpert** are lowest priority — advisory/forward-looking roles where generic guidance is acceptable.
+
+**Key insight:** Charters for code-producing agents (TypeScriptDev, TestEngineer, NodeJsDev) benefit most from codebase-specific enhancement because inaccuracies or gaps directly affect code quality. Advisory agents (OpenSourceExpert, ApicExpert) can remain more generic without harm.
+
 <!-- Append new learnings here after each session -->
+
+### 2026-05-01: Enhanced 7 Agent Charters with Codebase-Specific Patterns
+
+**What:** Applied the CodeReviewer charter enhancement pattern to all 7 remaining charters, making each codebase-aware with actual file paths, patterns, and team decisions.
+
+**Charters enhanced:**
+1. **TypeScriptDev** — Fixed inaccurate tsconfig claims (`noUncheckedIndexedAccess` removed, `ESNext` → `ES2022`), added correct strict flags, added "Tech-Specific Patterns" section with ESM, singleton+class export, error handling, interface-first design, opaque payloads, and key file paths table
+2. **TestEngineer** — Added "Codebase-Specific Testing Patterns" section with Vitest conventions, `IApimClient`/`IArtifactStore` mock interfaces, exit code testing, CLI subprocess tests, filesystem cleanup, error testing patterns, and review checklist
+3. **NodeJsDev** — Added "Codebase-Specific Patterns" section with exit code constants, ESM requirements, CLI entry point structure, dual-mode package consumption, generated template directories, and log-level decision
+4. **ApimExpert** — Added "Codebase Patterns" section with key source files table, `HttpError` pattern, retry/failure patterns, token caching, SOAP/WADL extraction, synthetic GraphQL detection, ARM URI construction, and 4 key decisions
+5. **AzdoExpert** — Added "Project-Specific Patterns" section with template source references, `apiops init` integration, and variable group conventions
+6. **GitHubExpert** — Added "Project-Specific Patterns" section with workflow file table, OIDC federation pattern, generated template references, and repo configuration
+7. **ApiOpsLead** — Added "What I Check" section with structural integrity, constitution alignment checklist, key decisions, and key file paths table; constitution path was already correct
+
+**Also fixed across all charters:**
+- Constitution path references updated to `.squad/identity/constitution.md` where stale
+- Collaboration sections updated to reference both constitution and decisions.md
+
+**Key insight:** The most impactful enhancements are on code-producing agents (TypeScriptDev, TestEngineer, NodeJsDev) where inaccurate or missing patterns directly cause code quality issues. The TypeScriptDev charter had two outright inaccuracies that would have led agents to write code targeting wrong settings.

.squad/agents/azdoexpert/charter.md

@@ -27,6 +27,25 @@
 - I know the Azure DevOps REST API when `az devops` doesn't cover it — I use `az devops invoke` for raw API calls.
 - I configure `az devops configure --defaults` to avoid repeating org/project on every command.
 
+### Project-Specific Patterns
+
+These patterns are specific to the apiops-cli project.
+
+#### Generated Pipeline Templates
+- `src/templates/azure-devops/` — Azure DevOps pipeline YAML templates generated by `apiops init`
+- Templates cover extract and publish workflows with proper variable group references
+- Generated pipelines use service connections for APIM authentication
+
+#### apiops init Integration
+- `apiops init` scaffolds Azure DevOps pipeline YAML when the user selects Azure DevOps as their CI/CD platform
+- Variable group naming follows APIM service connection conventions
+- Templates are rendered from `src/templates/azure-devops/` into the user's repository
+
+#### Variable Group Conventions
+- APIM service connection credentials go in variable groups, not inline pipeline variables
+- Secrets belong in variable groups linked to Key Vault — never hardcoded in YAML
+- Variable group names should follow the pattern established in the generated templates
+
 ## Key Commands I Use
 
 ```bash
@@ -71,7 +90,7 @@ az devops invoke --area {area} --resource {resource} --http-method GET
 
 Before starting work, run `git rev-parse --show-toplevel` to find the repo root, or use the `TEAM ROOT` provided in the spawn prompt. All `.squad/` paths must be resolved relative to this root.
 
-Before starting work, read `.squad/decisions.md` for team decisions that affect me.
+Before starting work, read `.squad/identity/constitution.md` and `.squad/decisions.md` for team decisions that affect me.
 After making a decision others should know, write it to `.squad/decisions/inbox/azdoexpert-{brief-slug}.md` — the Scribe will merge it.
 
 ## Voice

.squad/agents/codereviewer/history.md

@@ -4,7 +4,7 @@
 
 - **Project:** apiops-cli — A CLI tool for Azure API Management operations (extract, publish, init)
 - **Tech Stack:** TypeScript 5.x, Node.js 22+, Commander (CLI), Vitest (testing), ESLint (linting), ESM modules
-- **Constitution:** `.specify/memory/constitution.md` (v2.1.0) — 8 principles governing all development
+- **Constitution:** `.squad/identity/constitution.md` (v2.1.0) — 8 principles governing all development
 - **Speckit Flow:** spec → plan → tasks → implement
 - **Build:** `npm run build` (tsc), `npm run lint` (eslint), `npm test` (vitest)
 

.squad/agents/githubexpert/charter.md

@@ -27,6 +27,33 @@
 - I use `gh api` for anything not covered by dedicated `gh` commands — raw API access is essential.
 - I configure `gh auth login` with the right scopes upfront to avoid permission errors later.
 
+### Project-Specific Patterns
+
+These patterns are specific to the apiops-cli project.
+
+#### Repository Workflow Files
+| File | Purpose |
+|------|---------|
+| `.github/workflows/ci.yml` | CI pipeline — lint, build, test on PRs and pushes |
+| `.github/workflows/integration-test.yml` | Integration tests with OIDC federation against live Azure APIM |
+| `.github/workflows/codeql.yml` | CodeQL security analysis |
+| `.github/workflows/squad-*.yml` | Squad automation workflows for agent coordination |
+
+#### OIDC Federation Pattern
+- `integration-test.yml` uses `azure/login` with OIDC — no client secrets stored in GitHub
+- Federated credentials tied to the repository's environment (not repo-level secrets)
+- Environment protection rules gate integration test execution
+
+#### Generated GitHub Actions Templates
+- `src/templates/github-actions/` — GitHub Actions workflow YAML templates generated by `apiops init`
+- Templates cover extract and publish workflows for user repositories
+- `apiops init` scaffolds these when the user selects GitHub Actions as their CI/CD platform
+
+#### Repository Configuration
+- Branch protection on `main` — require PR reviews, status checks, linear history
+- Environment secrets for Azure APIM connection (managed identity / OIDC)
+- Dependabot configured for npm dependency updates
+
 ## Key Commands I Use
 
 ```bash
@@ -80,7 +107,7 @@ gh release upload {tag} {files}
 
 Before starting work, run `git rev-parse --show-toplevel` to find the repo root, or use the `TEAM ROOT` provided in the spawn prompt. All `.squad/` paths must be resolved relative to this root.
 
-Before starting work, read `.squad/decisions.md` for team decisions that affect me.
+Before starting work, read `.squad/identity/constitution.md` and `.squad/decisions.md` for team decisions that affect me.
 After making a decision others should know, write it to `.squad/decisions/inbox/githubexpert-{brief-slug}.md` — the Scribe will merge it.
 
 ## Voice