ai-squad 0.1.0

package/sections/opencode/agents/standards/python.md

@@ -0,0 +1,217 @@
+# Python Standards
+
+When working on `${PROJECT_NAME}` with Python, follow these conventions unless project context overrides.
+
+## Language Features
+
+**DO:**
+- Target Python ≥ 3.12 for all new projects — 3.13 is the stability baseline, 3.14 for performance/concurrency
+- Use `X | Y` union syntax (never `Union[X, Y]` or `Optional[X]`)
+- Use `match`/`case` structural pattern matching for complex branching on data shapes
+- Use deferred annotations — no `from __future__ import annotations` in 3.14+
+- Use `except*` for ExceptionGroups when concurrent code can raise multiple errors
+
+**DON'T:**
+- Don't use `Optional[X]` — use `X | None`
+- Don't use `from __future__ import annotations` — it's superseded in 3.14+
+- Don't rely on GIL-based thread safety in free-threaded Python 3.14+
+
+## Type Hints
+
+**DO:**
+- Use `Protocol` for structural subtyping — duck typing with static checking
+- Use `TypeIs` (3.13+) over `TypeGuard` — narrows in both branches
+- Use `@override` decorator (3.12+) on methods that override parent methods
+- Use `Literal["GET", "POST"]` for constrained string/int values
+- Use `Final` for constants and non-overridable methods
+- Use Pydantic `BaseModel` at system boundaries — API inputs, config files, DB records. Runtime validation, serialization, JSON schema
+- Use `dataclass(frozen=True)` for internal immutable data containers — zero runtime overhead
+- Use `TypedDict` for dict-shaped data — type-check dict keys at zero runtime cost
+- Run `mypy --strict` in CI — catches `Any` leakage, untyped defs, incomplete types
+- Consider running both mypy and pyright — they catch different error classes
+
+**DON'T:**
+- Don't use `Any` — it disables type checking. Use `object`, `Protocol`, or a `Union` instead
+- Don't use raw `dict` for structured data — use `TypedDict`, `dataclass`, or Pydantic
+- Don't use `dataclass` for external data validation — it does NOT validate at runtime
+- Don't annotate `self` or `cls` in method signatures
+- Don't use `# type: ignore` without a specific error code — use `# type: ignore[attr-defined]`
+
+## Tooling
+
+**DO:**
+- Use `uv` for package management — `uv init`, `uv add`, `uv lock`, `uv sync --frozen` in CI
+- Use Ruff for linting and formatting — `ruff check . --fix && ruff format .`
+- Configure everything in `pyproject.toml` — Ruff, mypy, pytest, coverage, build settings
+- Use pre-commit hooks — Ruff + mypy, catch issues in seconds not CI minutes
+- In CI: `uv sync --frozen && ruff check . && mypy --strict src/ && pytest -n auto --cov`
+
+**DON'T:**
+- Don't install tools globally — use `uv add --dev` and `uv run <tool>`
+- Don't keep `setup.py`, `setup.cfg`, `.flake8`, `mypy.ini`, `pytest.ini` — migrate to `pyproject.toml`
+- Don't use pip directly in new projects — `uv add` is the standard
+- Don't split configuration across multiple files
+
+## Project Structure
+
+**DO:**
+- Use the src layout — `src/my_package/` with sibling `tests/`, prevents accidental imports
+- Put all metadata in `pyproject.toml` — `[project]`, `[build-system]`, `[tool.*]`
+- Use `requires-python = ">=3.12"` in pyproject.toml
+- Separate integration tests from unit tests — `tests/integration/` with its own `conftest.py`
+- Keep `__init__.py` minimal — import key symbols, avoid heavy computation at import time
+
+**DON'T:**
+- Don't put test code in the package directory — shipped wheels should not include tests
+- Don't use `setup.py` — it's deprecated for configuration
+- Don't do heavy work at module import time — lazy-load expensive resources
+- Don't use `from module import *` — pollutes namespace, breaks static analysis
+
+## Code Style
+
+**DO:**
+- Follow PEP 8 — 4-space indentation, 100-char lines, snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants
+- Use imperative verbs for functions (`get_user`, `calculate_total`, `validate_email`), noun phrases for classes (`UserProfile`, `EmailValidator`)
+- Use `is_` / `has_` prefixes for boolean functions/properties
+- Use single leading underscore `_internal` for internal/private module members
+- Extract named constants for magic values — `TIMEOUT_SECONDS = 15`, not inline `15`
+
+**DON'T:**
+- Don't use single-letter variables except in comprehensions/loops (`i`, `k`, `v` only for trivial scopes)
+- Don't shadow builtins — never name variables `list`, `dict`, `id`, `type`, `str`, `input`
+- Don't use mixedCase — Python uses snake_case
+- Don't name modules with hyphens — use underscores (`my_package`, not `my-package`)
+- Don't use magic numbers — extract named constants
+
+## Data Structures
+
+| Use Case | Tool | Reason |
+|---|---|---|
+| API/DB models, untrusted input | **Pydantic BaseModel** | Runtime validation + serialization |
+| Internal data containers | **dataclass(frozen=True)** | Zero overhead, immutability |
+| Dict-shaped data (JSON configs) | **TypedDict** | Type-check keys at zero cost |
+| Priority queues | **heapq** | O(log n) push/pop |
+| FIFO/LIFO queues | **deque** | O(1) both ends |
+| Membership testing | **set** | O(1) vs O(n) for list |
+
+**DON'T:**
+- Don't use `list` as a queue — `list.pop(0)` is O(n), use `deque`
+- Don't use `list` for membership testing in hot loops — use `set`
+- Don't use raw `dict` for structured data with known keys
+- Don't use `NamedTuple` for large or mutable records — use `dataclass`
+
+## Error Handling
+
+**DO:**
+- Catch specific exceptions — `except ValueError`, never `except Exception` or bare `except:`
+- Create a custom exception hierarchy — one base exception per library/app
+- Chain exceptions with `raise ... from ...` — preserve the original cause
+- Use context managers for resource management — `with open(...) as f:`, `with transaction():`
+- Use `try`/`else` for code that runs only on success
+- Use `finally` for cleanup that MUST run
+- Log exceptions with `logger.exception()` — automatically includes traceback
+- Use assertions for programming errors (bugs), exceptions for runtime errors
+
+**DON'T:**
+- Don't catch and silently ignore — `except Exception: pass` is a bug. If you must suppress, log it
+- Don't use bare `except:` — catches `KeyboardInterrupt` and `SystemExit`
+- Don't use exceptions for control flow — exceptions are for exceptional cases
+- Don't raise `Exception` directly — raise a specific type or custom exception
+- Don't lose the traceback — use `raise` (re-raise) or `raise NewError(...) from original`
+- Don't use `assert` for input validation — assertions disappear with `python -O`
+
+## Testing
+
+**DO:**
+- Use pytest — configure in `pyproject.toml` under `[tool.pytest.ini_options]`
+- Centralize shared fixtures in `conftest.py` — auto-available to tests in that directory and below
+- Choose fixture scopes: `function` for mutable/cheap, `session` for expensive/read-only resources
+- Use `@pytest.mark.parametrize` with `ids` for readable multi-input tests
+- Follow Arrange-Act-Assert — structure every test into these three clear phases
+- One logical assertion per test — `test_apply_discount` tests discount, not inventory + email
+- In CI: `pytest -n auto --cov=src/ --cov-report=xml --cov-fail-under=85 --strict-markers -ra`
+- Install: `pytest-cov`, `pytest-xdist`, `pytest-mock`, `pytest-randomly`, `pytest-asyncio`
+
+**DON'T:**
+- Don't use `for` loops inside a single test — use `@parametrize`, loops hide which input failed
+- Don't let tests depend on execution order — each test must set up everything through fixtures
+- Don't skip `--strict-markers` — a typo'd marker becomes a silent no-op without it
+- Don't mock what you don't own — mock your own adapters, not the external library directly
+- Don't test implementation details — test behavior, not internal method calls
+
+## Performance & Async
+
+**DO:**
+- Use `async`/`await` for I/O-bound work — network calls, file I/O, database queries. Not CPU-bound
+- Prefer AnyIO over raw asyncio — fixes cancellation bugs, provides structured concurrency
+- Use structured concurrency — `async with anyio.create_task_group() as tg:`
+- Use `anyio.to_thread.run_sync()` for CPU-bound work in async contexts
+- Use generators for large datasets — `yield` items one at a time instead of building lists in memory
+- Profile before optimizing — use `cProfile` or `py-spy` to find actual bottlenecks
+
+**DON'T:**
+- Don't call blocking I/O inside `async def` — use async equivalents or `run_sync`
+- Don't create tasks without tracking them — unhandled task exceptions silently vanish in asyncio
+- Don't use `time.sleep()` in async code — use `await anyio.sleep()`
+- Don't use `asyncio.shield()` — it's a footgun, use AnyIO cancel scopes instead
+- Don't eagerly load large datasets into memory — use generators or lazy evaluation
+
+## Security
+
+**DO:**
+- Never use `eval()`, `exec()`, or `compile()` on untrusted input
+- Use `secrets` module for cryptographic randomness — `secrets.token_hex()`, not `random.random()`
+- Validate and sanitize all user input at boundaries — use Pydantic models for API inputs
+- Use parameterized queries for SQL — never string interpolation. SQLAlchemy/psycopg handle this
+- Check dependencies for vulnerabilities — run `uv pip check` or `pip-audit` regularly
+- Use `secrets.compare_digest()` for comparing tokens — constant-time comparison
+- Use `.env` files for local secrets — and `.gitignore` them. Use a secrets manager in production
+- Never log secrets, tokens, or passwords — redact sensitive fields from logs
+
+**DON'T:**
+- Don't use `pickle` on untrusted data — arbitrary code execution. Use JSON, msgpack, or protobuf
+- Don't use `subprocess` with `shell=True` — shell injection risk. Pass args as a list, `shell=False`
+- Don't hardcode secrets in source code — use environment variables or a secrets manager
+- Don't use `yaml.load()` without `SafeLoader` — `yaml.load()` can execute arbitrary code, use `yaml.safe_load()`
+- Don't construct SQL queries with string formatting — `f"SELECT * FROM users WHERE id = {user_id}"`
+- Don't skip TLS verification — `verify=False` in requests is a security hole
+- Don't expose stack traces to users — catch and handle exceptions at the API boundary
+
+## Anti-Patterns
+
+**DO:**
+- Use `pathlib.Path` instead of `os.path` — cleaner, cross-platform, object-oriented
+- Use f-strings instead of `.format()` or `%` formatting
+- Use `is` for `None`/`True`/`False` comparison — `x is None`, not `x == None`
+- Use `isinstance()` instead of `type()` for type checks — respects inheritance
+- Use `enumerate()` instead of `range(len(...))`
+- Use `zip()` for parallel iteration — not index-based loops
+- Default to immutability — `dataclass(frozen=True)`, `frozenset`
+
+**DON'T:**
+- Don't use mutable default arguments — `def f(lst=[])` is a classic trap, use `def f(lst=None): lst = lst or []`
+- Don't catch and swallow exceptions silently — `except: pass` is a bug
+- Don't use `from module import *` — pollutes namespace, hides origins
+- Don't use `global` — pass state explicitly or restructure
+- Don't use `if len(x) > 0` — just `if x:` (truthiness check)
+- Don't compare `None` with `==` — use `is None` / `is not None`
+- Don't put multiple statements on one line with `;` — one statement per line
+- Don't use list comprehensions with side effects — they're for building lists, not `[print(x) for x in items]`
+- Don't use `pip install` globally — always in a virtual environment managed by uv
+
+## Dependencies
+
+**DO:**
+- Use uv: `uv init`, `uv add`, `uv lock`, `uv sync --frozen` in CI
+- Commit your lock file — `uv.lock` (or `poetry.lock`) to version control for deterministic builds
+- List only direct dependencies — let the resolver figure out transitive deps
+- Separate dev from production dependencies — `uv add --dev pytest ruff mypy pre-commit`
+- Pin Python version — `requires-python = ">=3.12"` in pyproject.toml
+- Update dependencies intentionally — `uv lock --upgrade` as a deliberate step with testing
+
+**DON'T:**
+- Don't use `requirements.txt` as source of truth in new projects — use `pyproject.toml [project.dependencies]`
+- Don't pin transitive dependencies in your input file — only list packages you import
+- Don't keep unbounded dependency ranges — prefer `"django>=4.2,<6.0"` over unbounded `"django"`
+- Don't ignore `uv pip check` warnings — broken dependency constraints cause runtime failures
+- Don't skip dependency updates for months — stale deps accumulate CVEs

package/sections/opencode/agents/standards/react.md

@@ -0,0 +1,130 @@
+# React Standards
+
+When working on `${PROJECT_NAME}` with React, follow these conventions unless project context overrides.
+
+## Server Components (React 19+)
+
+**DO:**
+- Default to Server Components — only add `"use client"` when you need interactivity, state, effects, or browser APIs
+- Use `async/await` directly in Server Components for data fetching — no `useEffect`, no `useState` for loading state
+- Wrap async Server Components in `<Suspense>` boundaries with meaningful fallbacks
+- Keep sensitive logic server-only: database access, API keys, private env vars, filesystem reads
+- Fetch data in parallel at the component level — Server Components don't waterfall
+
+**DON'T:**
+- Do NOT use `useState`, `useEffect`, or browser APIs in Server Components
+- Do NOT import a Server Component into a Client Component — pass data as children or props instead
+- Do NOT use browser-locked libraries (`window`, `document`) in Server Components — wrap in a Client Component
+
+## Hooks
+
+**DO:**
+- Rely on the React Compiler for automatic memoization — write clean code, let the compiler optimize
+- Use `useCallback` only when: (1) child is wrapped in `React.memo`, (2) every prop is memoized, (3) the function reference change causes measurable re-renders
+- Use the updater function pattern to avoid stale closures: `setCount(prev => prev + 1)`
+- Use `useRef` for values that should not trigger re-renders
+- Clean up every subscription, timer, and event listener in `useEffect` return
+
+**DON'T:**
+- Do NOT wrap every function in `useCallback` "just in case" — 90% can be removed without regression
+- Do NOT compute derived state with `useEffect` + `useState` — compute it during render
+- Do NOT use `useEffect` for data fetching in Server Components — `async/await` is the pattern
+- Do NOT forget dependency arrays — stale closures cause subtle bugs
+- Do NOT use `index` as `key` when items can be reordered, added, or removed — use stable unique IDs
+
+## State Management
+
+**DO:**
+- Use `useState` for component-local UI state
+- Use `useReducer` for complex local state with interdependent transitions
+- Use Zustand for shared global state — selector-based subscriptions, ~1KB, no providers
+- Use TanStack Query (React Query) for server state — caching, background refetching, eliminates boilerplate
+- Use Context API for rarely-changing global values (theme, locale, auth status) — split by update frequency
+- Keep state as close to where it's used as possible — lift up only when multiple components need it
+
+**DON'T:**
+- Do NOT use Context API for high-frequency updates — all consumers re-render on every change
+- Do NOT duplicate server state in client state — TanStack Query is the source of truth for API data
+- Do NOT choose Redux by default for new projects — Zustand covers 90% of use cases with less boilerplate
+- Do NOT store derived values in state — compute them during render
+
+## Components
+
+**DO:**
+- Follow Single Responsibility — each component should have one reason to change
+- Use Compound Components for related components that share implicit state via Context
+- Extract business logic and data transforms into pure utility functions outside components
+- Extract reusable stateful logic into custom hooks
+- Use Error Boundaries wrapping major sections to prevent cascading crashes
+- Organize by feature, not by type: `features/auth/LoginForm.tsx` over `components/LoginForm.tsx`
+
+**DON'T:**
+- Do NOT put business logic in view components — components should orchestrate, hooks should compute
+- Do NOT deeply nest components without extracting — deep nesting hurts readability and testing
+- Do NOT use `index.ts` barrel exports excessively — they can cause circular dependencies
+- Do NOT create unnecessary wrapper `<div>`s — use fragments (`<>...</>`)
+- Do NOT forget to handle loading, empty, and error states in every data-dependent component
+
+## TypeScript
+
+**DO:**
+- Use generic components for reusable UI patterns: `function List<T>({ items }: { items: T[] })`
+- Use `ComponentPropsWithoutRef<'button'>` to extend native HTML element props
+- Use explicit event types: `React.ChangeEvent<HTMLInputElement>`, `React.MouseEvent<HTMLButtonElement>`
+- Export props interfaces alongside components: `export interface ButtonProps { ... }`
+- Enable `strict: true` in `tsconfig.json`
+
+**DON'T:**
+- Do NOT use `React.FC` as default typing — it implicitly adds `children`, prefer explicit prop types
+- Do NOT use `any` — use `unknown` and narrow types properly
+- Do NOT duplicate component types for different data shapes — use one generic component
+- Do NOT cast DOM events unnecessarily — use the proper handler types
+
+## Performance
+
+**DO:**
+- Enable the React Compiler — highest-impact, lowest-effort optimization (30-60% re-render reduction)
+- Route-based code splitting with `lazy` + `Suspense` — highest impact per effort
+- Virtualize large lists (50+ items) with `react-window` or `@tanstack/react-virtual`
+- Split contexts by update frequency — never bundle unrelated state in one context
+- Use `useDeferredValue` and `useTransition` for non-urgent updates
+- Optimize images: WebP/AVIF, responsive sizes, lazy loading, explicit dimensions
+
+**DON'T:**
+- Do NOT wrap everything in `React.memo` — only memoize components that re-render frequently with identical props
+- Do NOT use expensive CSS properties in animations — prefer `transform` and `opacity` (GPU-composited)
+- Do NOT ship Moment.js (300KB) — use `date-fns` or native `Intl.DateTimeFormat`
+- Do NOT skip memory leak prevention — always clean up timers, intervals, and listeners
+
+## Accessibility
+
+**DO:**
+- Use semantic HTML first: `<button>`, `<nav>`, `<main>`, `<form>` — they have built-in keyboard, role, and state support
+- Follow the First Rule of ARIA: if a native element does what you need, use it — don't add ARIA to semantic elements
+- Provide visible focus indicators — never remove `outline` without a custom replacement
+- Use `aria-label` or `aria-labelledby` for interactive elements without visible text labels
+- Use live regions for dynamic content: `<div aria-live="polite">`
+- Test with keyboard-only navigation
+
+**DON'T:**
+- Do NOT use `div` or `span` for interactive controls — use `<button>`, `<input>`, `<select>`
+- Do NOT use ARIA when HTML semantics suffice — "No ARIA is better than bad ARIA"
+- Do NOT use color alone to convey information — supplement with icons, text, or patterns
+- Do NOT skip `alt` text on images — `alt=""` for decorative, descriptive text for informational
+- Do NOT trap focus without an escape mechanism (Escape key to close modals)
+
+## Security
+
+**DO:**
+- Let JSX auto-escape dynamic content — curly braces `{}` are safe against XSS by default
+- Sanitize HTML with DOMPurify before using `dangerouslySetInnerHTML`
+- Validate URLs before rendering in `<a href>`: only allow `http:` and `https:` protocols
+- Store tokens in HTTP-only cookies, not localStorage
+- Implement Content Security Policy (CSP) headers to restrict script sources
+
+**DON'T:**
+- Do NOT use `dangerouslySetInnerHTML` on raw user input without DOMPurify sanitization
+- Do NOT use direct DOM manipulation to inject content — `ref.current.innerHTML = userContent`
+- Do NOT expose API keys, secrets, or sensitive config in client-side code — everything in bundles is public
+- Do NOT use `eval()` or `new Function()` with user-supplied input
+- Do NOT ship source maps in production

package/sections/opencode/agents/standards/typescript.md

@@ -0,0 +1,30 @@
+# TypeScript Standards
+
+When working on `${PROJECT_NAME}`, follow these TypeScript conventions unless `${PROJECT_NAME}`'s context docs say otherwise.
+
+## Configuration
+
+- Enable `strict: true` in `tsconfig.json` — no exceptions
+- Use `noUncheckedIndexedAccess` to catch undefined access
+- Prefer `es2022` or later as the compile target
+
+## Types
+
+- Prefer `interface` over `type` for object shapes — interfaces are extensible and produce better error messages
+- Use `type` for unions, intersections, and mapped types
+- Explicit return types on all exported functions — it catches accidental contract changes
+- Never use `any` without a comment explaining why it's unavoidable
+- Use `unknown` instead of `any` when the type is genuinely unknown
+- Use `const` assertions (`as const`) for literal types and tuple inference
+
+## Style
+
+- Prefer `as` casting over angle-bracket syntax — it's unambiguous with JSX
+- Use optional chaining (`?.`) and nullish coalescing (`??`) over verbose null checks
+- Prefer `readonly` arrays and properties where mutation isn't needed
+- Use template literal types for string patterns when applicable
+
+## Exports
+
+- Named exports only — no default exports (they break IDE auto-imports and refactoring)
+- Export prop interfaces alongside their components

package/sections/opencode/agents/workflow/context.md

@@ -0,0 +1,24 @@
+# Context Documentation
+
+${AGENT_NAME}, always ground yourself in `${PROJECT_NAME}`'s documented context before writing code.
+
+## Required Reading
+
+Before implementing anything, read these files in order:
+
+1. **`.agent/context/project/stack.md`** — The tech stack. Languages, frameworks, databases, third-party services. This is the source of truth for what the project uses. Don't guess.
+
+2. **`.agent/context/project/conventions.md`** — Project-specific conventions. File naming, directory structure, import ordering, formatting rules. Follow these exactly.
+
+3. **`.agent/context/project/architecture.md`** — High-level architecture. Component tree, data flow, API surface, deployment topology. Understand the system before changing it.
+
+## How to Use Context
+
+- Treat these files as ground truth — they override your default assumptions
+- If context and a standards section conflict, context wins (it's project-specific)
+- When you notice something missing from these docs, flag it to the user; don't silently diverge
+- If conventions say "use kebab-case for files," use kebab-case — don't improvise with camelCase because you prefer it
+
+## Cross-Referencing
+
+When context refers to patterns (e.g. "error handling follows the Result pattern"), check `.agent/memory/decisions.md` for the rationale behind those patterns.

package/sections/opencode/agents/workflow/memory.md

@@ -0,0 +1,32 @@
+# Memory Management
+
+${AGENT_NAME}, consult project memory before making decisions in `${PROJECT_NAME}`.
+
+## Before You Start
+
+Read these files before beginning any work:
+
+1. **`.agent/memory/decisions.md`** — Architectural decisions and their rationale. Every non-trivial choice made in the project should be recorded here with date, context, and reasoning.
+
+2. **`.agent/memory/conventions.md`** — Discovered conventions that aren't in the formal standards docs. These are patterns the team has settled on through practice (naming choices, file organization, error handling style).
+
+## When Making Decisions
+
+- Check `.agent/memory/decisions.md` first — has this already been decided?
+- Reference the relevant past decision by its date/ID when making a new one
+- If your decision reverses or modifies a past decision, explain why
+
+## Recording New Decisions
+
+After making a significant architectural choice, append to `.agent/memory/decisions.md`:
+
+```markdown
+## YYYY-MM-DD: Decision Title
+
+**Context:** What situation led to this decision
+**Decision:** What was chosen
+**Alternatives considered:** What else was evaluated and why it wasn't picked
+**Consequences:** What this enables and what it constrains
+```
+
+Keep entries factual. Don't record trivial choices like variable names.

package/sections/opencode/agents/workflow/sessions.md

@@ -0,0 +1,38 @@
+# Session Logging
+
+${AGENT_NAME}, log every session so `${PROJECT_NAME}` maintains a traceable history.
+
+## When to Log
+
+At the end of each work session — whether you completed tasks or not — write a session log.
+
+## Log Location
+
+Write to `.agent/sessions/YYYY-MM-DD.md`. If the file already exists (same-day continuation), append to it rather than overwriting.
+
+## Log Format
+
+```markdown
+# Session: YYYY-MM-DD
+
+**Agent:** ${AGENT_NAME}
+**Duration:** Brief estimate if known
+
+## Tasks Worked On
+- TASK-001: What was attempted or completed
+- TASK-002: Another item
+
+## Decisions Made
+- Decision summary and rationale (one line each)
+
+## Problems and Solutions
+- Problem encountered → How it was resolved
+- Open issues carried forward (if any)
+```
+
+## Guidelines
+
+- Keep entries factual and brief — these are logs, not documentation
+- Record problems even if you couldn't solve them; next sessions need to know
+- If nothing was accomplished, log that too (blocked, waiting, research-only)
+- Don't duplicate content already in `.agent/memory/decisions.md` — link to it instead

package/sections/opencode/agents/workflow/tasks.md

@@ -0,0 +1,40 @@
+# Task Management
+
+${AGENT_NAME}, use the task system to track your work in `${PROJECT_NAME}`.
+
+## Reading Tasks
+
+Task files live in `.agent/tasks/`. At startup, scan the directory for the current task:
+
+1. Look for a file matching `current.md` or `active.md` — that's your active task
+2. If none found, look for `backlog.md` and pick the next `[ ]` item
+3. If no tasks exist, ask the user what to work on
+
+## Task File Format
+
+Each task file follows this structure:
+
+```markdown
+# ${AGENT_NAME} Tasks
+
+## Active
+- [ ] TASK-001: Brief description of what needs doing
+  - Subtask detail if needed
+  - Another subtask
+
+## Completed
+- [x] TASK-000: Something already finished
+```
+
+## Marking Tasks Done
+
+When you complete a task:
+
+1. Change `[ ]` to `[x]` in the source file
+2. Move the completed line to the `## Completed` section
+3. If there are more tasks in `## Active`, pick the next one
+4. If the active section is empty, report completion to the user
+
+## Task Naming
+
+Use short, imperative descriptions: "Add authentication middleware", "Fix login redirect bug", "Update API types for user endpoint". Prefix with `TASK-NNN` if the project uses numbered tracking.

package/sections/opencode/config/agents.md

@@ -0,0 +1,11 @@
+# ${PROJECT_NAME}
+
+This project uses AI Squad agents for development. The following agents are available:
+
+${AGENT_LIST}
+
+## Workflow
+
+Before starting any task, read the current state and understand the project context.
+
+Always follow project conventions and architecture decisions.

package/sections/opencode/context/nextjs/architecture.md

@@ -0,0 +1,13 @@
+# Architecture — ${PROJECT_NAME}
+
+## Directory Structure
+Describe the top-level project layout here.
+
+## Data Flow
+Describe how data moves through the system (request → component → database).
+
+## Key Design Decisions
+Add entries here as architectural decisions are made. Reference `.agent/memory/decisions.md` for full ADRs.
+
+## External Services
+List any third-party APIs and how they integrate.

package/sections/opencode/context/nextjs/conventions.md

@@ -0,0 +1,20 @@
+# Conventions — ${PROJECT_NAME}
+
+## Code Style
+- Use TypeScript strict mode. No `any` without justification.
+- Prefer Server Components unless client interactivity is needed.
+- Use `kebab-case` for files, `PascalCase` for components.
+- Co-locate component tests alongside the component file.
+
+## Routing
+- App Router only. Group routes by feature in `(feature)` folders.
+- `page.tsx` is the route entry; keep it thin.
+
+## Data Fetching
+- Fetch in Server Components when possible.
+- Use React `cache()` for per-request deduplication.
+- Mutations go in Server Actions or API routes.
+
+## State
+- URL search params for shareable UI state.
+- Zustand or Jotai for complex client state (add to stack if used).

package/sections/opencode/context/nextjs/stack.md

@@ -0,0 +1,14 @@
+# Tech Stack — ${PROJECT_NAME}
+
+| Category | Technology |
+|----------|------------|
+| Framework | Next.js |
+| Language | TypeScript |
+| Styling | Tailwind CSS |
+| Database | — |
+| Auth | — |
+| Hosting | Vercel |
+| Testing | Vitest + Playwright |
+| Linting | ESLint + Prettier |
+
+Fill in the blanks as the project evolves.

package/sections/opencode/context/python/architecture.md

@@ -0,0 +1,13 @@
+# Architecture — ${PROJECT_NAME}
+
+## Directory Structure
+Describe the top-level project layout here.
+
+## Data Flow
+Describe how data moves through the system (request → handler → database).
+
+## Key Design Decisions
+Add entries here as architectural decisions are made. Reference `.agent/memory/decisions.md` for full ADRs.
+
+## External Services
+List any third-party APIs and how they integrate.

package/sections/opencode/context/python/conventions.md

@@ -0,0 +1,19 @@
+# Conventions — ${PROJECT_NAME}
+
+## Code Style
+- Follow PEP 8. Enforce with ruff and black.
+- Type hints on all function signatures. Run mypy in strict mode.
+- Use `snake_case` for files, functions, and variables.
+
+## Project Layout
+- `src/` layout preferred over flat `app/` layout.
+- Keep modules focused: one concern per module.
+
+## Error Handling
+- Use custom exception classes, not bare `Exception`.
+- Fail loudly in development, gracefully in production.
+
+## Testing
+- pytest with fixtures in `conftest.py`.
+- One test file per source module: `test_<module>.py`.
+- Aim for >80% coverage on business logic.

package/sections/opencode/context/python/stack.md

@@ -0,0 +1,14 @@
+# Tech Stack — ${PROJECT_NAME}
+
+| Category | Technology |
+|----------|------------|
+| Language | Python |
+| Package Manager | pip / Poetry |
+| Web Framework | FastAPI / Flask / Django |
+| Database | — |
+| ORM | — |
+| Testing | pytest |
+| Linting | ruff / black / mypy |
+| Hosting | — |
+
+Fill in the blanks as the project evolves.

package/sections/opencode/workflow/context.md

@@ -0,0 +1,14 @@
+# Context Management
+
+## Available Context Docs
+- `stack.md` — tech stack, tools, libraries. Read when choosing dependencies.
+- `conventions.md` — coding conventions. Read before writing code.
+- `architecture.md` — system design and data flow. Read for architectural context.
+
+## When to Read
+At the start of any implementation task, read `stack.md` and `conventions.md`. For system-level changes, also read `architecture.md`.
+
+## Maintenance
+- `stack.md` — updated by `squad-architect` when dependencies change
+- `conventions.md` — updated by `squad-memory-keeper` as new conventions emerge
+- `architecture.md` — updated by `squad-architect` for design changes

package/sections/opencode/workflow/memory.md

@@ -0,0 +1,12 @@
+# Memory Management
+
+## When to Read Memory
+Before starting any task, read `.agent/memory/decisions.md` and `.agent/memory/conventions.md` to understand past decisions and established patterns.
+
+## When to Append
+After making a technical decision, append to `decisions.md`. When a new convention emerges, append to `conventions.md`. Use the format specified in the templates.
+
+## Agent Ownership
+- `decisions.md` — maintained by `squad-architect` and `squad-memory-keeper`
+- `conventions.md` — maintained by `squad-memory-keeper`
+- `patterns.md` — maintained by `squad-architect` (Comprehensive only)