Skip to content

majiayu000/spellbook / skills/architecture-foundation

architecture-foundation

Verified

Design architecture foundations before implementation. Use when asked to design or refactor architecture, choose Rust/Go crate, package, module, runtime, workflow, or service boundaries, compare mature project architecture, prevent stacked one-off PRs, audit migration debt in existing repos, or produce a spec before coding.

references/spec-template.md

View on GitHub
# Architecture Foundation Spec Template

Use this template for a repo-facing architecture artifact. Keep it specific:
name files, modules, APIs, validation commands, and issue/PR links when known.

## Objective

State the product or engineering goal in one paragraph.

## Current Evidence

| Area | Evidence | Implication |
| --- | --- | --- |
| Entrypoints |  |  |
| Core models |  |  |
| Runtime/lifecycle |  |  |
| Adapters/backends |  |  |
| Generated/config artifacts |  |  |
| Errors/diagnostics |  |  |
| Tests/headless |  |  |
| Open issues/PRs |  |  |

## Reference Models Considered

| Reference | Borrow | Do not copy | Source |
| --- | --- | --- | --- |
|  |  |  |  |

## Chosen Shape

```text
product/app
  - 

core/domain
  - 

runtime/application
  - 

adapters/backends
  - 

plugins/components
  - 

testing/headless
  - 
```

## Source Of Truth And Migration Debt

| Contract | Current source of truth | Consumers | Duplicates or forks | Action |
| --- | --- | --- | --- | --- |
| Public API/schema |  |  |  |  |
| Runtime/workflow state |  |  |  |  |
| Billing/accounting state |  |  |  |  |
| Config/resources |  |  |  |  |
| Generated docs/examples |  |  |  |  |

## Boundary Contracts

| Contract | Owner | Allowed dependencies | Forbidden dependencies | Tests |
| --- | --- | --- | --- | --- |
| State ownership |  |  |  |  |
| Lifecycle |  |  |  |  |
| Events/actions |  |  |  |  |
| Effects/IO |  |  |  |  |
| Errors |  |  |  |  |
| Config/resources |  |  |  |  |
| Observability |  |  |  |  |
| Compatibility/API |  |  |  |  |

## Issue And PR Map

| Issue/PR | Contract served | Status | Gap or follow-up |
| --- | --- | --- | --- |
|  |  |  |  |

## Compatibility And Deletion Plan

| Path or shim | Why it exists | Owner | Keep until | Delete or converge when |
| --- | --- | --- | --- | --- |
|  |  |  |  |  |

## P0/P1/P2 Roadmap

| Priority | Work | Files/modules | Done when | Verification |
| --- | --- | --- | --- | --- |
| P0 |  |  |  |  |
| P1 |  |  |  |  |
| P2 |  |  |  |  |

## Non-Goals

- 

## Open Questions

- 

## Readiness Language

Use precise claims. Prefer:

- "The architecture spec is complete enough to sequence P0 work."
- "The runtime contract is implemented for headless tests."
- "The platform adapter exists for macOS only; other platforms return explicit
  unsupported errors."

Avoid:

- "Equivalent to X" without a feature matrix and fresh verification.
- "Production-ready" without tests, platform matrix, error policy, and docs.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall