create-project-arch 1.2.0 → 1.3.1

package/templates/architecture-specs/SPEC_TEMPLATE.md

@@ -0,0 +1,49 @@
+# System Architecture Specification
+
+<!-- Guidance: Use this template for new architecture specs in architecture/architecture/. -->
+
+## Purpose
+
+<!-- Guidance: Explain why this system/component exists and the problem it solves. -->
+
+...
+
+## Scope
+
+### In Scope
+
+- ...
+
+### Out Of Scope
+
+- ...
+
+## Key Definitions
+
+<!-- Guidance: Define domain terms and technical vocabulary used in this spec. -->
+
+- ...
+
+## Design
+
+<!-- Guidance: Describe architecture approach, constraints, and major patterns. -->
+
+...
+
+## Data Model
+
+<!-- Guidance: List core entities, relationships, and ownership boundaries. -->
+
+- ...
+
+## Owning Domain
+
+<!-- Guidance: Specify the domain accountable for this architecture area. -->
+
+- ...
+
+## MVP Constraints
+
+<!-- Guidance: List minimum viable boundaries and explicit non-goals for initial delivery. -->
+
+- ...

package/templates/architecture-specs/example-system.md

@@ -0,0 +1,42 @@
+# Example System Specification
+
+<!-- Guidance: Reference implementation of SPEC_TEMPLATE.md for new projects. -->
+
+## Purpose
+
+Provide a canonical architecture spec format for teams documenting a system surface.
+
+## Scope
+
+### In Scope
+
+- Define required architecture sections and ownership expectations.
+- Establish traceable spec structure for implementation planning.
+
+### Out Of Scope
+
+- Detailed API contract definitions.
+- Final production implementation decisions.
+
+## Key Definitions
+
+- System surface: a bounded capability area implemented across one or more modules.
+- Ownership boundary: the domain responsible for maintaining this surface.
+
+## Design
+
+Use a layered design where interface boundaries, data ownership, and dependency direction are explicit.
+
+## Data Model
+
+- `SpecSection`: named architecture section with required content.
+- `OwnershipLink`: maps the system surface to an owning domain.
+
+## Owning Domain
+
+- `core`
+
+## MVP Constraints
+
+- Keep scope focused on structure and traceability.
+- Defer advanced runtime behavior until downstream milestones.

package/templates/concept-map/concept-map.json

@@ -0,0 +1,67 @@
+{
+  "schemaVersion": "1.0",
+  "concepts": [
+    {
+      "id": "concept-identity-and-access",
+      "name": "Identity And Access",
+      "description": "Authentication, authorization, and role enforcement boundaries.",
+      "owningDomain": "core",
+      "moduleResponsibilities": ["packages/api", "packages/types"],
+      "implementationSurfaces": [
+        {
+          "type": "api",
+          "path": "packages/api/src/auth"
+        },
+        {
+          "type": "ui",
+          "path": "apps/web/app/(auth)"
+        }
+      ],
+      "dependencies": ["concept-user-profile"]
+    },
+    {
+      "id": "concept-user-profile",
+      "name": "User Profile",
+      "description": "Canonical user metadata and preference lifecycle.",
+      "owningDomain": "ui",
+      "moduleResponsibilities": ["apps/web", "packages/ui"],
+      "implementationSurfaces": [
+        {
+          "type": "ui",
+          "path": "apps/web/app/profile"
+        },
+        {
+          "type": "component",
+          "path": "packages/ui/src/profile"
+        }
+      ],
+      "dependencies": []
+    }
+  ],
+  "domainModuleMapping": [
+    {
+      "domain": "core",
+      "module": "packages/api",
+      "responsibility": "Policy enforcement and access control services"
+    },
+    {
+      "domain": "ui",
+      "module": "apps/web",
+      "responsibility": "User-facing workflows and interaction handling"
+    }
+  ],
+  "implementationChecklist": [
+    {
+      "conceptId": "concept-identity-and-access",
+      "checks": [
+        "Decision linkage recorded",
+        "Primary code targets identified",
+        "Verification criteria defined"
+      ]
+    },
+    {
+      "conceptId": "concept-user-profile",
+      "checks": ["Domain ownership confirmed", "Surface mapping completed", "Dependencies reviewed"]
+    }
+  ]
+}

package/templates/decisions/DECISION_TEMPLATE.md

@@ -0,0 +1,53 @@
+---
+id: "project:YYYYMMDD:decision-slug"
+title: "Decision Title"
+slug: "decision-slug"
+status: "proposed"
+createdAt: "YYYY-MM-DD"
+updatedAt: "YYYY-MM-DD"
+relatedTasks: []
+relatedDocs: []
+supersedes: []
+---
+
+## Decision Title
+
+<!-- Guidance: Capture one architecture decision per file. Keep scope explicit and testable. -->
+
+## Context
+
+<!-- Guidance: What problem/constraint requires a decision now? -->
+
+...
+
+## Decision
+
+<!-- Guidance: State the chosen approach unambiguously. -->
+
+...
+
+## Rationale
+
+<!-- Guidance: Why this option was selected versus alternatives. -->
+
+...
+
+## Alternatives Considered
+
+- Option A: ...
+- Option B: ...
+
+## Affected Artifacts
+
+<!-- Guidance: List code/doc surfaces impacted by this decision. -->
+
+- `packages/...`
+- `apps/...`
+- `architecture/...`
+
+## Implementation Status Checklist
+
+- [ ] Task links added
+- [ ] Code targets updated
+- [ ] Public docs updated
+- [ ] Validation checks pass

package/templates/decisions/README.md

@@ -0,0 +1,19 @@
+# Decision Records
+
+<!-- Guidance: Use decision records for meaningful architecture choices and tradeoffs. -->
+
+## Workflow
+
+1. Copy `DECISION_TEMPLATE.md` for each significant decision.
+2. Set frontmatter (`id`, `title`, `slug`, `status`, timestamps, links).
+3. Fill Context, Decision, Rationale, Alternatives, and Affected Artifacts.
+4. Track implementation progress with the checklist.
+
+## Decision Locations
+
+- `architecture/decisions/` for architecture-level decision records.
+- `roadmap/decisions/` and milestone decision indexes can reference decision IDs for execution traceability.
+
+## CLI Support
+
+Use `pa decision new` to create operational decision records linked into roadmap indexes.

package/templates/decisions/example-decision.md

@@ -0,0 +1,45 @@
+---
+id: "project:20260308:adopt-typed-service-contracts"
+title: "Adopt Typed Service Contracts"
+slug: "adopt-typed-service-contracts"
+status: "accepted"
+createdAt: "2026-03-08"
+updatedAt: "2026-03-08"
+relatedTasks:
+  - "phase-1/milestone-1-setup/005"
+relatedDocs:
+  - "architecture/architecture/example-system.md"
+supersedes: []
+---
+
+## Adopt Typed Service Contracts
+
+## Context
+
+Service integration points were drifting across modules due to implicit payload assumptions.
+
+## Decision
+
+All cross-module service boundaries must use explicit shared types in `packages/types` with runtime validation in API adapters.
+
+## Rationale
+
+Typed contracts reduce integration regressions, improve agent traceability, and make architectural intent machine-verifiable.
+
+## Alternatives Considered
+
+- Keep implicit JSON contracts and rely on integration tests only.
+- Use per-module ad hoc type aliases without shared contracts.
+
+## Affected Artifacts
+
+- `packages/types/src/`
+- `packages/api/src/`
+- `architecture/architecture/example-system.md`
+
+## Implementation Status Checklist
+
+- [x] Task links added
+- [x] Code targets updated
+- [x] Public docs updated
+- [x] Validation checks pass

package/templates/domains/DOMAIN_TEMPLATE.md

@@ -0,0 +1,43 @@
+# Domain Template
+
+<!-- Guidance: Copy this file to `<domain-name>.md` when introducing a new domain. -->
+
+## Domain Name
+
+<domain-name>
+
+## Responsibilities
+
+<!-- Guidance: What this domain owns and manages. -->
+
+- ...
+
+## Primary Data Ownership
+
+<!-- Guidance: Entities this domain is the source of truth for. -->
+
+- ...
+
+## Interface Contracts
+
+<!-- Guidance: APIs/events this domain exposes and consumes. -->
+
+- ...
+
+## Non-Goals
+
+<!-- Guidance: Explicit boundaries for what this domain does NOT do. -->
+
+- ...
+
+## Milestone Mapping
+
+<!-- Guidance: Map milestones to domain delivery outcomes. -->
+
+- milestone-1: ...
+- milestone-2: ...
+
+## Implementation Surfaces
+
+- `apps/...`
+- `packages/...`

package/templates/domains/README.md

@@ -0,0 +1,18 @@
+# Domain Specifications
+
+<!-- Guidance: Define domain boundaries first, then map implementation surfaces and ownership. -->
+
+This directory contains domain ownership artifacts for architecture-first planning.
+
+## What To Maintain
+
+- `domains.json` - machine-readable domain registry
+- `DOMAIN_TEMPLATE.md` - template for new domains
+- `core.md`, `ui.md`, `api.md` - starter domain examples
+
+## Workflow
+
+1. Update `domains.json` when adding/removing a domain.
+2. Create or update a corresponding `<domain>.md` file.
+3. Keep ownership and interface contracts aligned with `arch-model/modules.json`.
+4. Reference milestone rollout in each domain spec.

package/templates/domains/api.md

@@ -0,0 +1,33 @@
+# API Domain
+
+<!-- Guidance: Service boundaries, data access, and system integration behavior. -->
+
+## Responsibilities
+
+- Define service interfaces and orchestration policies.
+- Own data access boundaries and integration adapters.
+
+## Primary Data Ownership
+
+- Persistence models and storage interfaces
+- Service-level request/response contracts
+
+## Interface Contracts
+
+- API functions consumed by apps
+- Data-access contracts consumed by orchestration logic
+
+## Non-Goals
+
+- Rendering UI components
+- Owning cross-cutting presentation concerns
+
+## Milestone Mapping
+
+- milestone-1-foundation: establish service boundaries and data model assumptions
+- milestone-2-build: implement core API adapters and persistence flows
+
+## Implementation Surfaces
+
+- `packages/api`
+- `packages/database`

package/templates/domains/core.md

@@ -0,0 +1,33 @@
+# Core Domain
+
+<!-- Guidance: Shared domain model, policies, and cross-cutting foundations. -->
+
+## Responsibilities
+
+- Define shared domain concepts and invariants.
+- Own cross-cutting configuration and type contracts.
+
+## Primary Data Ownership
+
+- Canonical shared types
+- Environment and runtime configuration schema
+
+## Interface Contracts
+
+- Shared type exports consumed by UI/API domains
+- Configuration contracts used across packages
+
+## Non-Goals
+
+- Rendering user interface components
+- Implementing transport-specific API adapters
+
+## Milestone Mapping
+
+- milestone-1-foundation: establish canonical types/config and boundaries
+- milestone-2-build: stabilize contracts used by runtime features
+
+## Implementation Surfaces
+
+- `packages/types`
+- `packages/config`

package/templates/domains/domains.json

@@ -0,0 +1,19 @@
+{
+  "domains": [
+    {
+      "name": "core",
+      "ownedPackages": ["packages/types", "packages/config"],
+      "ownedFeatures": ["domain-model", "shared-policies"]
+    },
+    {
+      "name": "ui",
+      "ownedPackages": ["apps/web", "apps/docs", "packages/ui"],
+      "ownedFeatures": ["user-experience", "design-system"]
+    },
+    {
+      "name": "api",
+      "ownedPackages": ["packages/api", "packages/database"],
+      "ownedFeatures": ["service-contracts", "data-access"]
+    }
+  ]
+}

package/templates/domains/ui.md

@@ -0,0 +1,34 @@
+# UI Domain
+
+<!-- Guidance: User-facing workflows and presentation-layer behavior. -->
+
+## Responsibilities
+
+- Deliver user journeys in web/docs applications.
+- Own component composition and interaction flows.
+
+## Primary Data Ownership
+
+- View models for page-level UX states
+- Design-system usage conventions
+
+## Interface Contracts
+
+- UI contracts against API/domain services
+- Shared component contracts in the UI package
+
+## Non-Goals
+
+- Persisting domain data directly
+- Defining backend data access policies
+
+## Milestone Mapping
+
+- milestone-1-foundation: baseline information architecture and navigation
+- milestone-2-build: implement key user workflows and feedback states
+
+## Implementation Surfaces
+
+- `apps/web`
+- `apps/docs`
+- `packages/ui`

package/templates/foundation/goals.md

@@ -0,0 +1,35 @@
+# Project Goals
+
+<!-- Guidance: Define measurable outcomes used to evaluate implementation decisions. -->
+
+Source: `architecture/foundation/prompt.md`
+
+## Primary Goals
+
+<!-- Guidance: Add launch-critical goals with measurable success criteria. -->
+
+- ...
+
+## Secondary Goals
+
+<!-- Guidance: Add valuable but non-blocking goals for post-launch improvement. -->
+
+- ...
+
+## Success Metrics
+
+<!-- Guidance: Include concrete signals (latency, adoption, completion rate, etc.) for each primary goal. -->
+
+- ...
+
+## Assumptions
+
+- ...
+
+## Unknowns
+
+- ...
+
+## Risks
+
+- ...

package/templates/foundation/project-overview.md

@@ -0,0 +1,35 @@
+# Project Overview
+
+<!-- Guidance: Summarize what the project is, why it exists, and who it serves. Derive this from prompt.md. -->
+
+Source: `architecture/foundation/prompt.md`
+
+## Problem Statement
+
+<!-- Guidance: Describe the user/business pain this project solves. -->
+
+...
+
+## Intended Users
+
+<!-- Guidance: Identify primary users and stakeholders who benefit from this system. -->
+
+...
+
+## Value Proposition
+
+<!-- Guidance: State why this solution is better than alternatives in one concise paragraph. -->
+
+...
+
+## Assumptions
+
+- ...
+
+## Unknowns
+
+- ...
+
+## Risks
+
+- ...

package/templates/foundation/prompt.md

@@ -0,0 +1,23 @@
+# Setup Prompt
+
+<!-- Guidance: Paste the original product brief, request, or requirements doc below. This is the canonical source for all other foundation docs. -->
+
+This file is the canonical source used to derive:
+
+- `project-overview.md`
+- `goals.md`
+- `user-journey.md`
+- `scope.md`
+
+## Prompt Status
+
+- [ ] Replaced template text with real project prompt
+- [ ] Prompt includes purpose, users, constraints, and non-goals
+
+## Source Prompt
+
+<!-- Guidance: Replace this block with your actual prompt content. Keep enough detail for architecture planning. -->
+
+```md
+PASTE_FOUNDATIONAL_PROMPT_HERE
+```

package/templates/foundation/scope.md

@@ -0,0 +1,35 @@
+# Scope And Non-Scope
+
+<!-- Guidance: Define explicit boundaries for what this phase will and will not deliver. -->
+
+Source: `architecture/foundation/prompt.md`
+
+## In Scope
+
+<!-- Guidance: List concrete capabilities that are required for this phase. -->
+
+- ...
+
+## Out Of Scope
+
+<!-- Guidance: List explicit exclusions to prevent scope creep. -->
+
+- ...
+
+## Constraints
+
+<!-- Guidance: Note constraints that shape delivery (team, time, budget, compliance, platform). -->
+
+- ...
+
+## Assumptions
+
+- ...
+
+## Unknowns
+
+- ...
+
+## Risks
+
+- ...

package/templates/foundation/user-journey.md

@@ -0,0 +1,37 @@
+# User Journey
+
+<!-- Guidance: Capture the end-to-end flow from first touch to successful outcome. -->
+
+Source: `architecture/foundation/prompt.md`
+
+## Journey Steps
+
+<!-- Guidance: Describe the primary happy path in ordered steps. -->
+
+1. ...
+2. ...
+3. ...
+
+## Key Scenarios
+
+<!-- Guidance: Include important alternate paths (errors, retries, permission constraints). -->
+
+- ...
+
+## User Outcomes
+
+<!-- Guidance: Define what success looks like for the user at the end of the journey. -->
+
+- ...
+
+## Assumptions
+
+- ...
+
+## Unknowns
+
+- ...
+
+## Risks
+
+- ...

package/templates/gap-closure/GAP_CLOSURE_TEMPLATE.md

@@ -0,0 +1,50 @@
+# Milestone Gap-Closure Report Template
+
+<!-- Guidance: Use this at milestone completion to document closure quality and residual risk. -->
+
+## Executive Summary
+
+<!-- Guidance: One paragraph summarizing closure outcome and release readiness. -->
+
+...
+
+## Gap Categories And Resolutions
+
+<!-- Guidance: Group identified gaps by category and note final resolution status. -->
+
+- Gap category: ...
+  - Finding: ...
+  - Resolution: ...
+  - Status: closed | partially-closed | open
+
+## Layer Synchronization Check
+
+<!-- Guidance: Verify architecture, roadmap, and implementation surfaces remain aligned. -->
+
+- [ ] Architecture docs updated
+- [ ] Roadmap tasks/decisions synchronized
+- [ ] Graph/parity checks pass (`pa check`)
+- [ ] Report diagnostics reviewed (`pa report`)
+
+## Coverage Audit
+
+<!-- Guidance: Confirm milestone requirements/specs are fully addressed or explicitly deferred. -->
+
+- Requirement/spec: ...
+  - Coverage status: covered | deferred | partial
+  - Notes: ...
+
+## Remaining Gaps And Follow-On Items
+
+<!-- Guidance: List unresolved items and where they are tracked next. -->
+
+- Remaining gap: ...
+  - Follow-on task/decision: ...
+
+## Template Improvement Feedback
+
+<!-- Guidance: Capture scaffold/process improvements discovered while executing this milestone. -->
+
+- Improvement idea: ...
+  - Rationale: ...
+  - Proposed change: ...