create-project-arch 1.1.0 → 1.3.0

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: ...

package/templates/gap-closure/README.md

@@ -0,0 +1,19 @@
+# Milestone Gap-Closure Reports
+
+<!-- Guidance: Use these reports to complete milestone governance and quality review. -->
+
+## When To Use
+
+Create/update a closure report when a milestone reaches completion readiness.
+
+## Workflow
+
+1. Copy `GAP_CLOSURE_TEMPLATE.md` into the milestone or reference location.
+2. Fill each section with concrete findings and evidence.
+3. Run validation commands (`pa check`, `pa report`) and record outcomes.
+4. Track unresolved items as follow-on tasks/decisions.
+
+## Suggested Locations
+
+- `architecture/reference/` for reusable report artifacts and examples
+- `roadmap/phases/<phase>/milestones/<milestone>/closure.md` for milestone-specific closure records

package/templates/gap-closure/example-gap-closure.md

@@ -0,0 +1,43 @@
+# Milestone Gap-Closure Report - Example
+
+## Executive Summary
+
+Milestone scope is complete, critical architecture artifacts are synchronized, and remaining low-risk gaps are tracked for the next milestone.
+
+## Gap Categories And Resolutions
+
+- Traceability drift
+  - Finding: concept-map dependencies were incomplete for one feature cluster.
+  - Resolution: updated `arch-model/concept-map.json` and linked missing surfaces.
+  - Status: closed
+- Documentation clarity
+  - Finding: architecture scope language was ambiguous for one boundary.
+  - Resolution: clarified in architecture spec and referenced decision note.
+  - Status: closed
+
+## Layer Synchronization Check
+
+- [x] Architecture docs updated
+- [x] Roadmap tasks/decisions synchronized
+- [x] Graph/parity checks pass (`pa check`)
+- [x] Report diagnostics reviewed (`pa report`)
+
+## Coverage Audit
+
+- Spec section: service boundary constraints
+  - Coverage status: covered
+  - Notes: validated against acceptance checks and policy explain output.
+- Spec section: advanced optimization strategy
+  - Coverage status: deferred
+  - Notes: deferred to next milestone to protect launch scope.
+
+## Remaining Gaps And Follow-On Items
+
+- Remaining gap: deferred optimization strategy details
+  - Follow-on task/decision: roadmap task `phase-2/milestone-2-performance/003`
+
+## Template Improvement Feedback
+
+- Improvement idea: add explicit section for policy conflict outcomes
+  - Rationale: closure reviews repeatedly reference policy findings
+  - Proposed change: add "Policy Findings" subsection to template

package/templates/validation-hooks/.githooks/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+set -eu
+
+sh scripts/validate.sh

package/templates/validation-hooks/README.md

@@ -0,0 +1,20 @@
+# Validation Hook Scaffold
+
+This scaffold adds baseline architecture validation automation.
+
+## Included Files
+
+- `scripts/validate.sh` - local validation entrypoint
+- `.githooks/pre-commit` - optional local pre-commit hook example
+
+## Default Workflow
+
+1. Run `sh scripts/validate.sh` locally.
+2. The script executes:
+   - `pnpm arch:check`
+   - `pnpm arch:report`
+3. Optionally run the same script from `.githooks/pre-commit` for local enforcement.
+
+## Task Verification Guidance
+
+When writing or reviewing roadmap tasks, include architecture validation in acceptance checks and verification steps.

package/templates/validation-hooks/scripts/validate.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+set -eu
+
+echo "Running architecture validation..."
+
+pnpm arch:check
+pnpm arch:report > architecture-report.txt
+
+echo "Architecture validation complete."