Implement Spec

Implement Spec — Community Modules

Implements a specification (or selected phases) end-to-end inside a packages/<name>/ workspace. Every community module is an external extension — use UMES extension points exclusively. NEVER modify packages/core, packages/ui, packages/shared, or any other core package.

Pre-Flight

1. Identify the spec: Locate the target spec file in .ai/specs/.
2. Check scaffold: Verify packages/<name>/ exists and has been scaffolded (package.json, build.mjs, src/modules/<moduleId>/index.ts). If not, run the scaffold-module skill first.
3. Load context: Read the spec fully. Read AGENTS.md at repo root.
4. Load code-review checklist: Read .ai/skills/implement-spec/references/code-review-compliance.md.
5. Scope phases: If the user specifies phases (e.g. "phases 1-2"), implement only those. Otherwise implement all phases sequentially.

Golden Rule

Community modules NEVER modify core. They extend it.

Available UMES extension points:

Implementation Workflow

For each phase in the spec, execute these steps in order:

Step 1 — Plan the Phase

Read the phase from the spec. For each step:

• Identify files to create or modify inside packages/<name>/
• Map each file to the correct auto-discovery path (see AGENTS.md)
• Identify required imports (@open-mercato/shared, @open-mercato/ui, @open-mercato/core)
• Note cross-module interactions (which events to subscribe to, which widget slots to inject into)

Present a brief plan before writing code.

Step 2 — Implement

Use subagents liberally to parallelize independent work:

• One subagent per independent file when files have no dependencies
• Sequential for dependent files (entity → validator → API route → backend page)

Code-review rules to enforce inline:

Step 3 — Unit Tests

For every new function or class:

• Create tests in src/modules/<moduleId>/__tests__/
• Test happy path + key edge cases + error paths
• Mock DI services and external dependencies
• Verify: yarn workspace @open-mercato/<package-name> test

Step 4 — Sandbox Smoke Test

After each phase that adds API endpoints or UI pages:

# Validate the default installed flow
yarn registry:up
yarn publish:preview
yarn mercato module add @open-mercato/<package-name>@preview
yarn mercato db:migrate
yarn dev

If the package is intended to be ejectable, also validate --eject:

yarn mercato module add @open-mercato/<package-name>@preview --eject

Navigate to the relevant page and verify it renders and functions correctly.

Step 5 — Documentation

• Add/update i18n locale files for new keys
• If new entities with user-facing text: create src/modules/<moduleId>/translations.ts
• Run yarn generate after adding new module convention files
• Update README.md module table entry if the description changed

Step 6 — Self-Review (Code-Review Gate)

Before marking a phase complete, scan for violations:

# Inside packages/<name>/
grep -rn ": any" src/           # No `any` types
grep -rn "fetch(" src/          # No raw fetch
grep -rn "em\.find\b" src/      # Should be findWithDecryption
grep -rn "alert(" src/          # Should be flash()
grep -rn "<button" src/         # Should be Button/IconButton primitive

Fix all violations before proceeding.

Step 7 — Update Spec with Progress

After completing each phase, append/update ## Implementation Status in the spec:

## Implementation Status

| Phase | Status | Date | Notes |
|-------|--------|------|-------|
| Phase 1 — Foundation | Done | 2026-03-20 | Entities, ACL, setup |
| Phase 2 — API routes | In Progress | 2026-03-21 | GET done, POST pending |
| Phase 3 — UI pages | Not Started | — | — |

Step 8 — Verification

After all targeted phases are complete:

yarn workspace @open-mercato/<package-name> build    # must pass
yarn workspace @open-mercato/<package-name> typecheck # must pass
yarn workspace @open-mercato/<package-name> test      # must pass

Report results. Fix any failures before declaring done.

Subagent Strategy

Concurrency rule: parallel subagents for independent files only; sequential for dependent chains.

Rules

• MUST read the full spec before starting
• MUST check that scaffold exists before writing business logic
• MUST use UMES extension points — never modify core packages
• MUST enforce all code-review rules inline during implementation
• MUST pass self-review scan before marking a phase done
• MUST update the spec with implementation progress after each phase
• MUST run build + typecheck + test after final phase
• MUST NOT introduce any types, hardcoded strings, raw fetch, or em.find without decryption
• MUST NOT modify files in packages/core/, packages/ui/, packages/shared/
• MUST keep subagents focused — one task per subagent