create-project-arch 1.1.0 → 1.3.0

package/templates/arch-ui/components/inspector.tsx

@@ -119,7 +119,9 @@ function isTaskLikeType(type: string): type is "task" | "milestone" | "phase" {
   return type === "task" || type === "milestone" || type === "phase";
 }
 
-function isFileBackedType(type: string): type is "task" | "milestone" | "phase" | "domain" | "file" {
+function isFileBackedType(
+  type: string,
+): type is "task" | "milestone" | "phase" | "domain" | "file" {
   return (
     type === "task" ||
     type === "milestone" ||
@@ -190,7 +192,11 @@ function humanizeValue(label: string, value: string): string {
   return value;
 }
 
-function parseTaskId(taskId: string): { phaseId?: string; milestoneId?: string; taskNumber?: string } {
+function parseTaskId(taskId: string): {
+  phaseId?: string;
+  milestoneId?: string;
+  taskNumber?: string;
+} {
   const [phaseId, milestoneId, taskNumber] = taskId.split("/");
   return {
     phaseId: phaseId || undefined,
@@ -393,23 +399,21 @@ function MetadataDetails({
       className="rounded-lg border border-slate-700/70 bg-slate-900/30 p-2 [&_summary::-webkit-details-marker]:hidden"
       open={defaultOpen}
     >
-      <summary className="cursor-pointer list-none text-sm font-medium text-slate-200">{title}</summary>
+      <summary className="cursor-pointer list-none text-sm font-medium text-slate-200">
+        {title}
+      </summary>
       <div className="mt-2 grid gap-2">{children}</div>
     </details>
   );
 }
 
-function MetadataValue({
-  label,
-  value,
-}: {
-  label: string;
-  value: FrontmatterValue;
-}) {
+function MetadataValue({ label, value }: { label: string; value: FrontmatterValue }) {
   if (value === null) {
     return (
       <div className="grid gap-1">
-        <p className="m-0 text-xs uppercase tracking-[0.06em] text-slate-400">{humanizeLabel(label)}</p>
+        <p className="m-0 text-xs uppercase tracking-[0.06em] text-slate-400">
+          {humanizeLabel(label)}
+        </p>
         <p className="m-0 text-sm text-slate-500">None</p>
       </div>
     );
@@ -419,7 +423,9 @@ function MetadataValue({
     if (value.length === 0) {
       return (
         <div className="grid gap-1">
-          <p className="m-0 text-xs uppercase tracking-[0.06em] text-slate-400">{humanizeLabel(label)}</p>
+          <p className="m-0 text-xs uppercase tracking-[0.06em] text-slate-400">
+            {humanizeLabel(label)}
+          </p>
           <p className="m-0 text-sm text-slate-500">None</p>
         </div>
       );
@@ -428,7 +434,9 @@ function MetadataValue({
     const listLike = normalizeKey(label).includes("criteria");
     return (
       <div className="grid gap-1.5">
-        <p className="m-0 text-xs uppercase tracking-[0.06em] text-slate-400">{humanizeLabel(label)}</p>
+        <p className="m-0 text-xs uppercase tracking-[0.06em] text-slate-400">
+          {humanizeLabel(label)}
+        </p>
         {listLike ? (
           <ol className="m-0 grid list-decimal gap-1 pl-5 text-sm text-slate-200">
             {value.map((item) => (
@@ -485,7 +493,11 @@ export function InspectorPanel() {
       keys
         .filter((key) => sourceEntries.has(key))
         .map((key) => [key, sourceEntries.get(key) ?? null] as const)
-        .filter(([, value]) => showEmptyFileMetadata || !(value === null || (Array.isArray(value) && value.length === 0)));
+        .filter(
+          ([, value]) =>
+            showEmptyFileMetadata ||
+            !(value === null || (Array.isArray(value) && value.length === 0)),
+        );
 
     return {
       identity: pick(keyOrder.identity),
@@ -651,9 +663,15 @@ export function InspectorPanel() {
     <aside className="h-full min-h-0 overflow-y-auto overflow-x-visible border-l border-slate-800 bg-slate-950/85 p-4">
       <div className="grid gap-3">
         <div className="flex flex-wrap items-center gap-2">
-          <Badge variant="secondary">{humanizeLabel(hasFileDocument ? "file" : selection.type)}</Badge>
-          {typeof fileLaneValue === "string" ? <Badge variant="secondary">{humanizeValue("lane", fileLaneValue)}</Badge> : null}
-          {typeof fileStatusValue === "string" ? <Badge variant="secondary">{humanizeValue("status", fileStatusValue)}</Badge> : null}
+          <Badge variant="secondary">
+            {humanizeLabel(hasFileDocument ? "file" : selection.type)}
+          </Badge>
+          {typeof fileLaneValue === "string" ? (
+            <Badge variant="secondary">{humanizeValue("lane", fileLaneValue)}</Badge>
+          ) : null}
+          {typeof fileStatusValue === "string" ? (
+            <Badge variant="secondary">{humanizeValue("status", fileStatusValue)}</Badge>
+          ) : null}
           {selectedLevelFile?.path ? (
             <Button
               variant="outline"
@@ -687,7 +705,9 @@ export function InspectorPanel() {
         {graphWarnings.length > 0 ? (
           <Section title="Graph Diagnostics">
             {graphWarnings.slice(0, 8).map((issue, index) => (
-              <Code key={`${issue.ruleId}:${index}`}>[{issue.ruleId}] {issue.message}</Code>
+              <Code key={`${issue.ruleId}:${index}`}>
+                [{issue.ruleId}] {issue.message}
+              </Code>
             ))}
           </Section>
         ) : null}
@@ -774,7 +794,11 @@ export function InspectorPanel() {
                   {fileMetadataGroups.references.length > 0 ? (
                     <MetadataDetails title="References">
                       {fileMetadataGroups.references.map(([label, value]) => (
-                        <MetadataValue key={`file-references:${label}`} label={label} value={value} />
+                        <MetadataValue
+                          key={`file-references:${label}`}
+                          label={label}
+                          value={value}
+                        />
                       ))}
                     </MetadataDetails>
                   ) : null}
@@ -806,7 +830,11 @@ export function InspectorPanel() {
               <div className="grid gap-1.5">
                 <p className="text-slate-400">Task Metadata</p>
                 {rawTaskMetadata.map((item) => (
-                  <Field key={`${item.label}:${item.value}`} label={item.label} value={item.value} />
+                  <Field
+                    key={`${item.label}:${item.value}`}
+                    label={item.label}
+                    value={item.value}
+                  />
                 ))}
               </div>
             ) : null}
@@ -836,7 +864,9 @@ export function InspectorPanel() {
               {trace?.files?.map((file) => (
                 <Code key={file}>{file}</Code>
               ))}
-              {!trace?.decisionRefs?.length && !trace?.moduleRefs?.length && !trace?.files?.length ? (
+              {!trace?.decisionRefs?.length &&
+              !trace?.moduleRefs?.length &&
+              !trace?.files?.length ? (
                 <p className="text-slate-400">No trace links found.</p>
               ) : null}
             </div>
@@ -854,7 +884,11 @@ export function InspectorPanel() {
                 <div className="grid gap-2">
                   <p className="text-slate-400">Entity Data</p>
                   {entityDetails.summary.map((item) => (
-                    <Field key={`${item.label}:${item.value}`} label={item.label} value={item.value} />
+                    <Field
+                      key={`${item.label}:${item.value}`}
+                      label={item.label}
+                      value={item.value}
+                    />
                   ))}
                   <RelatedList label="Tasks" values={entityDetails.relatedTasks} />
                   <RelatedList label="Milestones" values={entityDetails.relatedMilestones} />

package/templates/arch-ui/components/sidebar.tsx

@@ -81,12 +81,17 @@ function sortTree(nodes: TreeNode[]): TreeNode[] {
   }));
 }
 
-function buildDocNodes(scope: DomainDocsData["docs"][number]["scope"], docs: DomainDocsData["docs"]): TreeNode[] {
+function buildDocNodes(
+  scope: DomainDocsData["docs"][number]["scope"],
+  docs: DomainDocsData["docs"],
+): TreeNode[] {
   const scopedDocs = docs.filter((doc) => doc.scope === scope);
   const roots: TreeNode[] = [];
 
   for (const doc of scopedDocs) {
-    const relativePath = doc.path.startsWith(`${scope}/`) ? doc.path.slice(scope.length + 1) : doc.path;
+    const relativePath = doc.path.startsWith(`${scope}/`)
+      ? doc.path.slice(scope.length + 1)
+      : doc.path;
     const parts = relativePath.split("/").filter(Boolean);
     if (parts.length === 0) continue;
 
@@ -162,7 +167,8 @@ export function Sidebar() {
   }, []);
 
   const activeView = useMemo<WorkspaceView>(() => {
-    if (pathname === "/work" && searchParams.get("view") === "architecture") return "architecture-map";
+    if (pathname === "/work" && searchParams.get("view") === "architecture")
+      return "architecture-map";
     if (pathname === "/work" && searchParams.get("view") === "project") return "project-map";
     if (pathname === "/work") return "tasks-roadmap";
     const view = searchParams.get("view");
@@ -290,9 +296,7 @@ export function Sidebar() {
           ) : (
             <span className="h-4 w-4" />
           )}
-          <span className="text-slate-300">
-            {iconForNode(node, expandedKeys.has(node.key))}
-          </span>
+          <span className="text-slate-300">{iconForNode(node, expandedKeys.has(node.key))}</span>
           <button
             type="button"
             className="min-w-0 flex-1 truncate text-left text-[12px] text-slate-200"
@@ -405,8 +409,14 @@ export function Sidebar() {
 
       <NavigationMenu>
         <section className="mb-4">
-          <p className="mb-2 text-[11px] uppercase tracking-[0.1em] text-slate-400">Unified Explorer</p>
-          {tree.length > 0 ? renderTree(tree) : <p className="text-sm text-slate-400">Loading explorer...</p>}
+          <p className="mb-2 text-[11px] uppercase tracking-[0.1em] text-slate-400">
+            Unified Explorer
+          </p>
+          {tree.length > 0 ? (
+            renderTree(tree)
+          ) : (
+            <p className="text-sm text-slate-400">Loading explorer...</p>
+          )}
         </section>
         <section className="mb-4">
           <p className="mb-2 text-[11px] uppercase tracking-[0.1em] text-slate-400">Node Filters</p>

package/templates/arch-ui/components/topbar.tsx

@@ -32,7 +32,8 @@ export function Topbar({ projectName }: { projectName: string }) {
   const pathname = usePathname();
   const searchParams = useSearchParams();
   const { selection } = useInspector();
-  const { splitPane, setSplitPane, rightCollapsed, setRightCollapsed, resetLayout } = useWorkspace();
+  const { splitPane, setSplitPane, rightCollapsed, setRightCollapsed, resetLayout } =
+    useWorkspace();
 
   useEffect(() => {
     function onKeyDown(event: KeyboardEvent) {
@@ -79,11 +80,7 @@ export function Topbar({ projectName }: { projectName: string }) {
 
   const breadcrumbs = useMemo(() => {
     const pathLabel =
-      pathname === "/work"
-          ? "Work Graph"
-          : pathname === "/health"
-            ? "Health"
-            : "Workspace";
+      pathname === "/work" ? "Work Graph" : pathname === "/health" ? "Health" : "Workspace";
     const view = searchParams.get("view");
     const secondary =
       view === "docs"
@@ -92,11 +89,11 @@ export function Topbar({ projectName }: { projectName: string }) {
           ? "Decisions"
           : view === "architecture"
             ? "Architecture"
-          : view === "project"
-            ? "Project"
-          : view === "tasks"
-            ? "Tasks"
-            : "Map";
+            : view === "project"
+              ? "Project"
+              : view === "tasks"
+                ? "Tasks"
+                : "Map";
 
     const parts = [pathLabel];
     if (pathname === "/work") parts.push(secondary);

package/templates/arch-ui/components/work-table.tsx

@@ -31,11 +31,7 @@ export function WorkTable({ tasks, onSelectTask }: WorkTableProps) {
       </TableHeader>
       <TableBody>
         {tasks.map((task) => (
-          <TableRow
-            className="cursor-pointer"
-            key={task.id}
-            onClick={() => onSelectTask(task)}
-          >
+          <TableRow className="cursor-pointer" key={task.id} onClick={() => onSelectTask(task)}>
             <TableCell>
               <Code>{task.id}</Code>
             </TableCell>

package/templates/arch-ui/components/workspace-context.tsx

@@ -84,7 +84,8 @@ function defaultFilters(): WorkspaceFilters {
 
 function resolveActiveGraphView(pathname: string, searchParams: URLSearchParams): GraphViewMode {
   if (pathname === "/work" && searchParams.get("view") === "project") return "project";
-  if (pathname === "/work" && searchParams.get("view") === "architecture") return "architecture-map";
+  if (pathname === "/work" && searchParams.get("view") === "architecture")
+    return "architecture-map";
   if (pathname === "/work") return "tasks";
   return "architecture-map";
 }

package/templates/arch-ui/eslint.config.js

@@ -1,2 +1,2 @@
-import { config } from '@repo/eslint-config/next-js';
-export default config;
+import { nextJsConfig } from '@repo/eslint-config/next-js';
+export default nextJsConfig;

package/templates/arch-ui/lib/graph-dataset.ts

@@ -114,14 +114,10 @@ async function filterGitIgnoredPaths(root: string, paths: string[]): Promise<Set
       if (chunk.length === 0) continue;
 
       try {
-        const { stdout } = (await execFile(
-          "git",
-          ["check-ignore", ...chunk],
-          {
-            cwd: root,
-            encoding: "utf8",
-          } as Parameters<typeof execFile>[2],
-        )) as { stdout: string };
+        const { stdout } = (await execFile("git", ["check-ignore", ...chunk], {
+          cwd: root,
+          encoding: "utf8",
+        } as Parameters<typeof execFile>[2])) as { stdout: string };
         stdout
           .split("\n")
           .map((line: string) => line.trim())

package/templates/arch-ui/lib/graph-schema.ts

@@ -229,10 +229,7 @@ export const GRAPH_VALIDATION_RULES = [
   },
 ] as const;
 
-function pushIssue(
-  output: GraphValidationResult,
-  issue: GraphValidationIssue,
-) {
+function pushIssue(output: GraphValidationResult, issue: GraphValidationIssue) {
   if (issue.severity === "error") output.errors.push(issue);
   else output.warnings.push(issue);
 }

package/templates/arch-ui/package.json

@@ -35,4 +35,3 @@
     "typescript": "5.9.2"
   }
 }
-

package/templates/arch-ui/tsconfig.json

@@ -8,14 +8,6 @@
     ],
     "strictNullChecks": true
   },
-  "include": [
-    "**/*.ts",
-    "**/*.tsx",
-    "**/*.d.ts",
-    "next-env.d.ts",
-    "next.config.js"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}
+  "include": ["**/*.ts", "**/*.tsx", "**/*.d.ts", "next-env.d.ts", "next.config.js"],
+  "exclude": ["node_modules"]
+}

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/...`