docs: improve onboarding and add AGENTS contract

Author: dtsong

AGENTS.md

@@ -0,0 +1,88 @@
+# AGENTS
+
+This repository is a portable OpenCode setup: it provides reusable agents, skills, commands, scripts, and workspace context.
+
+This file is the canonical development contract for both:
+- humans contributing to this repo
+- AI agents operating inside this repo
+
+## Repository Concepts
+
+- `agents/`: agent prompt files (roles like `architect`, `skeptic`, `craftsman`)
+- `skills/`: structured skill docs (repeatable workflows/templates)
+- `commands/`: reusable command docs (often mapped to scripts)
+- `scripts/`: executable workflow helpers
+- `workspaces/`: repo-name keyed context templates that OpenCode can inject
+- `profiles/`: optional capability bundles with a registry + manifests
+- `docs/`: onboarding, playbooks, and reference material
+
+The installer (`install.sh`) symlinks these directories into `~/.config/opencode/`.
+
+## Authoring Contracts
+
+### Skills
+
+Each `skills/*/SKILL.md` should include:
+- Purpose
+- Inputs
+- Process
+- Output Format
+- Quality Checks
+
+Keep skills:
+- practical (focused on reducing rework)
+- composable (usable alongside other skills)
+- stable (avoid needless churn that breaks muscle memory)
+
+### Agents
+
+Each `agents/*.md` should define:
+- mission (what the agent is for)
+- required inputs (what it needs from the user/repo)
+- workflow (ordered steps)
+- tool boundaries (what it must/must not do)
+- output contract (how it reports results)
+- anti-patterns (what to avoid)
+
+Keep agents:
+- narrow (one dominant responsibility)
+- explicit about safety boundaries
+- consistent across runs (avoid prompt drift)
+
+## Local Validation Checklist
+
+Run these before opening a PR:
+
+```bash
+# lightweight repo-wide checks
+python3 -m pip install --user pre-commit
+pre-commit install
+pre-commit run --all-files
+
+# shell script syntax checks
+bash -n install.sh
+bash -n scripts/*.sh
+
+# stack-aware quality gate detection for this repo
+./scripts/ops-check.sh
+```
+
+If you changed council-lite artifacts or workflows, also run:
+
+```bash
+./scripts/validate-council-lite.sh --latest
+```
+
+## Safety And Hygiene
+
+- Do not commit secrets or local-only credentials.
+- Prefer minimal diffs; avoid drive-by refactors.
+- Do not use destructive git commands unless explicitly requested.
+- Keep docs accurate: if behavior changes, update `README.md` and the relevant `docs/*.md`.
+
+## References
+
+- Default execution runbook: `docs/gpt53-opencode-playbook.md`
+- Workflows and scripts: `docs/workflows-playbook.md`
+- Agent usage patterns: `docs/agents-playbook.md`
+- Profiles and installer behavior: `docs/profiles.md`

README.md

@@ -2,13 +2,20 @@
 
 Portable OpenCode + Codex setup inspired by `my-claude-setup`.
 
-This repository is a practical starter for:
+This repository is for people who use OpenCode and want a reproducible, versioned setup they can reuse across machines:
 - reusable agents
 - structured skills
 - workspace-aware project context
 - session handover workflow
 - command-style execution playbooks
 
+## Prerequisites
+
+- OpenCode installed: https://opencode.ai/docs (install script: https://opencode.ai/install)
+- `git`, `bash`, and `python3` available on your PATH
+- Optional (contributors): `pre-commit`
+- Optional (GitHub workflows): `gh` authenticated (`gh auth login`)
+
 ## Quick Start
 
 ```bash
@@ -18,6 +25,13 @@ chmod +x install.sh
 ./install.sh
 ```
 
+Verify it worked:
+
+```bash
+./install.sh --status
+./scripts/ops-check.sh
+```
+
 ## Profiles
 
 This setup supports optional profiles:
@@ -67,6 +81,31 @@ Use `--conflict-policy skip` to leave conflicting paths untouched and continue l
 
 `./install.sh --uninstall` removes managed symlinks and profile state.
 
+## Try It Now
+
+```bash
+# create a session handover note in ./memory
+./scripts/handover.sh
+
+# quick repo-local quality gate detection
+./scripts/ops-check.sh
+
+# git helper
+./scripts/git-porcelain.sh status
+
+# issue -> branch -> draft PR loop (requires gh auth)
+./scripts/issue-pr-loop.sh start 123 main
+./scripts/issue-pr-loop.sh pr 123 main
+```
+
+If you enabled `council-lite`, you can also run:
+
+```bash
+./scripts/council-lite.sh run "Design safe billing webhooks"
+./scripts/council-lite.sh list
+./scripts/validate-council-lite.sh --latest
+```
+
 ## Directory Layout
 
 ```text
@@ -113,3 +152,23 @@ Use `docs/gpt53-opencode-playbook.md` as the default runbook for GPT-5.3 + OpenC
 - launch checklist in `docs/open-source-launch.md`
 - friend outreach message in `docs/friend-outreach-template.md`
 - onboarding feedback channels in `docs/onboarding-feedback.md`
+
+## Where To Go Next
+
+- Profiles and installer behavior: `docs/profiles.md`
+- Common scripts and usage patterns: `docs/workflows-playbook.md`
+- Agent pack overview and how to invoke agents: `docs/agents-playbook.md` and `agents/README.md`
+- Mapping from Claude setup patterns: `docs/what-maps-what.md` and `docs/migration-from-claude.md`
+
+## Troubleshooting
+
+Conflicts under `~/.config/opencode/`:
+- If a managed path already exists and is not a symlink, install fails by default.
+- Recommended: move/remove the conflicting path, then rerun `./install.sh`.
+- If you want to proceed without replacing conflicting paths, use `./install.sh --conflict-policy skip`.
+
+"I expected files to be copied":
+- This repo is designed around symlinks. Editing files in this repo updates your OpenCode config immediately.
+
+"python3 not found":
+- Install requires `python3` for profile resolution and state management.