Format repository and add APS module specs

.oxfmtrc.json

@@ -0,0 +1,3 @@
+{
+  "ignorePatterns": []
+}

plans/modules/compound.aps.md

@@ -0,0 +1,47 @@
+# Compound Module
+
+| ID       | Owner  | Priority | Status |
+| -------- | ------ | -------- | ------ |
+| COMPOUND | @aneki | medium   | Draft  |
+
+## Purpose
+
+Capture reusable learnings from completed APS work so knowledge compounds
+across projects instead of staying buried in one-off plans.
+
+## In Scope
+
+- Solution document template
+- Review/Learn phase guidance
+- Linking completed work items to reusable decisions, patterns, or solutions
+- Repository-local solution library conventions
+
+## Out of Scope
+
+- Hosted knowledge base
+- AI model training datasets
+- Automatic semantic search
+
+## Interfaces
+
+**Depends on:**
+
+- ORCH — optional learning capture may feed this module later
+
+**Exposes:**
+
+- `templates/solution.template.md`
+- `plans/decisions/`
+- Future solution-library documentation
+
+## Work Items
+
+### COMPOUND-001: Define solution library workflow — Draft
+
+- **Intent:** Make post-work learning capture repeatable
+- **Expected Outcome:** Documentation explains when to create a solution doc,
+  how to link it from modules/work items, and how to avoid duplicating ADRs.
+- **Validation:** Apply workflow to one completed APS repo change and link it
+  from the relevant module
+- **Files:** templates/solution.template.md, docs/workflow.md, plans/decisions/
+- **Confidence:** medium

plans/modules/docs.aps.md

@@ -0,0 +1,47 @@
+# Documentation Module
+
+| ID   | Owner  | Priority | Status   |
+| ---- | ------ | -------- | -------- |
+| DOCS | @aneki | high     | Complete |
+
+## Purpose
+
+Document the APS workflow clearly enough that users can adopt it without
+reading every template or prompt.
+
+## In Scope
+
+- Getting started guide
+- Installation guide
+- Workflow guide
+- Monorepo guide
+- AI agent guide
+- Terminology and contribution guidance
+
+## Out of Scope
+
+- Hosted docs site
+- Tool-specific plugin documentation outside APS-owned integrations
+
+## Interfaces
+
+**Exposes:**
+
+- `README.md`
+- `docs/getting-started.md`
+- `docs/installation.md`
+- `docs/workflow.md`
+- `docs/monorepo.md`
+- `docs/ai-agent-guide.md`
+- `docs/TERMINOLOGY.md`
+
+## Work Items
+
+### DOCS-001: Publish onboarding documentation — Complete
+
+- **Intent:** Make common APS workflows discoverable
+- **Expected Outcome:** Documentation covers installation, plan authoring,
+  execution, and agent collaboration with examples.
+- **Validation:** `npx markdownlint-cli "**/*.md"`
+- **Files:** README.md, docs/
+- **Confidence:** high

plans/modules/dogfood.aps.md

@@ -0,0 +1,82 @@
+# Dogfood Module
+
+| ID      | Owner  | Priority | Status      |
+| ------- | ------ | -------- | ----------- |
+| DOGFOOD | @aneki | high     | In Progress |
+
+## Purpose
+
+Make this repository a credible APS example by keeping its own roadmap and
+module specs accurate, linked, current, and validated.
+
+## Background
+
+The public roadmap referenced modules that did not exist in `plans/modules/`.
+That undermines APS as a planning format: users should be able to inspect this
+repo and see the same discipline we recommend elsewhere.
+
+## In Scope
+
+- Every linked module in `plans/index.aps.md` has a corresponding module spec
+- Active modules include actionable work items with validation
+- Completed modules retain concise historical specs rather than disappearing
+- Plan updates are included with changes that affect APS templates, prompts,
+  examples, installer behavior, or validation behavior
+- Markdown linting remains the baseline verification for plan edits
+
+## Out of Scope
+
+- Rewriting historical completed modules in exhaustive detail
+- Replacing the roadmap with generated output
+- Implementing ORCH automation before ORCH work is selected
+
+## Interfaces
+
+**Depends on:**
+
+- VAL — plan files must be lintable
+
+**Exposes:**
+
+- `plans/index.aps.md` as the authoritative roadmap
+- `plans/modules/*.aps.md` as the complete module registry
+
+## Ready Checklist
+
+- [x] Purpose and scope are clear
+- [x] Dependencies identified
+- [x] Decisions resolved
+- [x] Work items defined with validation
+
+## Work Items
+
+### DOGFOOD-001: Reconcile roadmap module links — In Progress
+
+- **Intent:** Remove broken plan references from the public roadmap
+- **Expected Outcome:** Every markdown link in the Modules tables points to an
+  existing module spec, and every active module has a current status.
+- **Validation:** `./bin/aps lint plans && npx markdownlint-cli "plans/**/*.md"`
+- **Files:** plans/index.aps.md, plans/modules/\*.aps.md
+- **Confidence:** high
+
+### DOGFOOD-002: Define plan hygiene checks — Ready
+
+- **Intent:** Make stale APS plans detectable before they drift again
+- **Expected Outcome:** A documented checklist or lint enhancement verifies
+  index-to-module link integrity, active work item status, and required
+  validation fields for non-complete work.
+- **Validation:** Check runs locally and fails on a deliberately broken module
+  link in a fixture or temporary test project
+- **Files:** lib/lint.sh, lib/Lint.psm1, test/fixtures/, docs/workflow.md
+- **Confidence:** medium
+- **Dependencies:** DOGFOOD-001
+
+### DOGFOOD-003: Add contribution guidance for APS plan updates — Ready
+
+- **Intent:** Make plan updates part of normal repo contribution hygiene
+- **Expected Outcome:** `AGENTS.md` and contributor docs say when APS plan files
+  must be updated, how to mark work item status, and what validation to run.
+- **Validation:** `npx markdownlint-cli "AGENTS.md" "CONTRIBUTING.md" "docs/**/*.md"`
+- **Files:** AGENTS.md, CONTRIBUTING.md, docs/workflow.md
+- **Confidence:** high
+- **Dependencies:** DOGFOOD-001

plans/modules/examples.aps.md

@@ -0,0 +1,41 @@
+# Examples Module
+
+| ID       | Owner  | Priority | Status |
+| -------- | ------ | -------- | ------ |
+| EXAMPLES | @aneki | medium   | Draft  |
+
+## Purpose
+
+Provide worked APS examples that demonstrate realistic planning structures,
+execution plans, decisions, and design documents.
+
+## In Scope
+
+- Example projects for small features and multi-module work
+- Valid action plans under `examples/*/execution/`
+- Example design documents and decisions
+- Fixtures that double as validation coverage where practical
+
+## Out of Scope
+
+- Large fake applications
+- Generated examples with no explanatory value
+
+## Interfaces
+
+**Exposes:**
+
+- `examples/user-auth/`
+- `examples/opencode-companion/`
+- `test/fixtures/valid/`
+
+## Work Items
+
+### EXAMPLES-001: Expand worked examples — Draft
+
+- **Intent:** Show APS in more than one project shape and tool workflow
+- **Expected Outcome:** Examples cover single-feature, multi-module, agent-led,
+  and execution-plan workflows with valid markdown.
+- **Validation:** `./bin/aps lint examples test/fixtures/valid`
+- **Files:** examples/, test/fixtures/valid/
+- **Confidence:** medium

plans/modules/integrations.aps.md

@@ -0,0 +1,47 @@
+# Integrations Module
+
+| ID           | Owner  | Priority | Status |
+| ------------ | ------ | -------- | ------ |
+| INTEGRATIONS | @aneki | low      | Draft  |
+
+## Purpose
+
+Explore low-lock-in integrations that expose APS plans to external workflows
+without making external systems the source of truth.
+
+## In Scope
+
+- JSON export from APS markdown
+- GitHub issue or project sync experiments
+- GitHub Action wrapper around validation
+- Read-only integration patterns that preserve markdown as canonical
+
+## Out of Scope
+
+- Jira, Linear, or Notion plugins
+- Hosted sync service
+- Bidirectional sync that can overwrite APS markdown without review
+
+## Interfaces
+
+**Depends on:**
+
+- VAL — export and action checks need parser behavior
+- ORCH — status/dependency commands may provide structured data later
+
+**Exposes:**
+
+- Future `aps export` command
+- Future GitHub Action documentation
+
+## Work Items
+
+### INTEGRATIONS-001: Define JSON export shape — Draft
+
+- **Intent:** Let external tools consume APS without owning APS state
+- **Expected Outcome:** Documented JSON shape for index, modules, work items,
+  dependencies, statuses, files, and validation commands.
+- **Validation:** Prototype export against `plans/` and `examples/` produces
+  stable JSON suitable for CI or GitHub sync experiments
+- **Files:** docs/, bin/aps, lib/lint.sh, lib/Lint.psm1
+- **Confidence:** low

plans/modules/prompts.aps.md

@@ -0,0 +1,43 @@
+# Prompts Module
+
+| ID      | Owner  | Priority | Status |
+| ------- | ------ | -------- | ------ |
+| PROMPTS | @aneki | medium   | Draft  |
+
+## Purpose
+
+Maintain APS prompting entry points for generic agents and tool-specific
+harnesses without drifting away from the shared APS lifecycle.
+
+## In Scope
+
+- Generic index, module, work item, and actions prompts
+- OpenCode-specific prompt variants
+- Claude Code orchestration prompts
+- Guidance for when tool-specific variants should exist versus linking back to
+  generic prompts
+
+## Out of Scope
+
+- Full agent packaging, which belongs to AGENT
+- Prompt marketplace distribution
+
+## Interfaces
+
+**Exposes:**
+
+- `docs/ai/prompting/*.prompt.md`
+- `docs/ai/prompting/opencode/*.prompt.md`
+- `docs/ai/prompting/claudecode/*.prompt.md`
+
+## Work Items
+
+### PROMPTS-001: Normalize prompt variants — Draft
+
+- **Intent:** Keep tool-specific prompts consistent with the generic APS rules
+- **Expected Outcome:** Prompt variants clearly state their tool-specific
+  differences and otherwise defer to shared APS concepts.
+- **Validation:** Review prompt variants for duplicated stale rules; markdownlint
+  passes for `docs/ai/prompting/`
+- **Files:** docs/ai/prompting/
+- **Confidence:** medium

plans/modules/scaffold.aps.md

@@ -0,0 +1,43 @@
+# Scaffold Module
+
+| ID       | Owner  | Priority | Status   |
+| -------- | ------ | -------- | -------- |
+| SCAFFOLD | @aneki | high     | Complete |
+
+## Purpose
+
+Provide the initial APS project scaffold so users can create a working
+`plans/` directory with templates, rules, and starter documentation.
+
+## In Scope
+
+- Starter `plans/index.aps.md`
+- Module, simple feature, monorepo, issue, action, design, and solution templates
+- Initial shell installer entry point
+- Portable markdown-first layout
+
+## Out of Scope
+
+- Interactive customization beyond the initial shell prompts
+- Multi-tool agent packaging
+- Native binary distribution
+
+## Interfaces
+
+**Exposes:**
+
+- `scaffold/plans/index.aps.md`
+- `scaffold/plans/modules/`
+- `templates/*.template.md`
+- `scaffold/init.sh`
+
+## Work Items
+
+### SCAFFOLD-001: Create starter plan scaffold — Complete
+
+- **Intent:** Let new projects start with a valid APS structure
+- **Expected Outcome:** Scaffold contains starter index, module templates, and
+  supporting planning files.
+- **Validation:** Fresh scaffold passes `./bin/aps lint scaffold/plans`
+- **Files:** scaffold/plans/, templates/
+- **Confidence:** high