docs: add repository structure and contributor guidelines

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Problem
+
+<!-- Explain the concrete problem or link its issue. For a bug, include the trigger and root cause. -->
+
+## Changes
+
+<!-- Describe the resulting behavior and the relevant implementation choices. Keep this proportional to the change. -->
+
+## Behavior and compatibility
+
+<!-- Cover changed defaults, accepted inputs, prompts, persisted data, public interfaces, and their consumers. Explain migration or escape paths. For documentation-only changes, state what guidance changes and whether runtime behavior is affected. -->
+
+## Validation
+
+<!-- List exact commands and outcomes, relevant platforms, and intentional skips. Include the required repository-wide checks. Do not claim checks that were not run. -->
+
+## Limitations
+
+<!-- State remaining risks, unverified behavior, or pending CI. Write None when there are no additional limitations to report. -->

AGENTS.md

@@ -9,3 +9,139 @@
 - Before creating or amending a commit, inspect its metadata and remove any AI-client attribution trailer.
 
 This policy applies to commit metadata. Documentation may mention AI products when that is relevant to the product or feature being documented.
+
+## 1. Scope and reading order
+
+This file defines repository-wide rules for Step-Code. Before changing a directory, also read the `AGENTS.md` files in that directory and its ancestors. Local rules add module constraints; they cannot override this file's commit attribution policy, dependency direction, or public-source boundary.
+
+- `CLAUDE.md` continues to reference this file; do not maintain a second set of repository rules.
+- Organize architecture guidance around layers, responsibilities, and ownership. Verify paths, dependencies, commands, and defaults against current source, `package.json`, check scripts, and the relevant documentation.
+- Check implementation status before borrowing designs from other repositories. Do not copy obsolete paths, unimplemented plans, or private branch and release procedures.
+
+## 2. Project structure and dependency layers
+
+The current source layout is:
+
+```text
+apps/
+  cli/                         Process entry points and interactive host
+    src/args/                  Arguments and mode selection
+    src/bootstrap/             Startup composition
+    src/commands/              Top-level commands
+    src/modes/                 Mode routing
+    src/bun/                   Standalone binary entry
+    src/ui/                    UI host, runtime, and views
+packages/
+  agent-core/                  Generic Agent runtime
+    src/harness/               Sessions, context, compaction, and generic tools
+    src/search/                Generic search
+  coding-agent/                Coding product and SDK
+    src/core/                  Product session mechanisms, tools, and extensions
+    src/features/              Plan, task, subagent, workflow, goal, and cron
+    src/step/                  Step configuration, permissions, MCP, and integrations
+    src/modes/                 Non-interactive execution
+    src/server/                Host service adapters
+    src/theme/                 Product themes
+    src/render/                Rendering helpers
+    src/components/            Reusable product components
+    docs/                      Package APIs and usage
+    examples/                  SDK and extension examples
+    test/                      Product and session regressions
+  config/                      Product-neutral startup migrations
+  contracts/                   Independent host interfaces and wire frames
+  providers/                   Model access, adapters, catalogs, and credentials
+  telemetry/                   Telemetry contracts and reference implementations
+  tui/                         Terminal input, layout, and rendering
+docs/                          Repository-wide guides and runtime contracts
+scripts/                       Checks, generators, builds, and development tools
+infra/release/                 Local packaging and installer templates
+plugins/                       Built-in marketplace and plugin declarations
+.github/                       Public CI workflows and contribution templates
+.husky/                        Git hook definitions
+```
+
+Package manifests and `scripts/workspace-registry.json` define workspace membership; build outputs and installed dependencies are not source modules. Read the [development and collaboration guide](docs/development.md) for implementation practices and [testing policy](docs/testing.md) to select validation.
+
+Dependencies flow from product entry points toward foundational capabilities. Foundational packages must not depend on products or applications. The table defines allowed internal dependencies, not a requirement to depend on every listed package.
+
+| Layer | Module and local rules | Responsibility | Allowed internal dependencies |
+| --- | --- | --- | --- |
+| Foundation | [telemetry](packages/telemetry/AGENTS.md) | Telemetry contracts, typed schemas, no-op and in-memory reference implementations | None |
+| Foundation | [tui](packages/tui/AGENTS.md) | Terminal input, layout, differential rendering, and generic components | None |
+| Foundation | [contracts](packages/contracts/AGENTS.md) | In-process host/Agent interfaces, wire events, and framing | None; runtime dependencies must remain empty |
+| Foundation | [config](packages/config/AGENTS.md) | Product-neutral configuration migrations | None |
+| Model runtime | [providers](packages/providers/AGENTS.md) | Providers, API dialects, model catalogs, credentials, and vendor adapters | telemetry |
+| Agent runtime | [agent-core](packages/agent-core/AGENTS.md) | The single Agent Loop, generic harness, session and context semantics | providers, telemetry |
+| Coding product | [coding-agent](packages/coding-agent/AGENTS.md) | Coding sessions, tool policies, extensions, orchestration, Step integrations, and themes | agent-core, providers, config, tui |
+| Application host | [apps/cli](apps/cli/AGENTS.md) | argv, startup composition, mode routing, process lifecycle, and interactive UI | coding-agent, agent-core, providers, config, tui |
+
+- Register new workspaces in `pnpm-workspace.yaml`, root `package.json`, and `scripts/workspace-registry.json`. Use the `@step-harness/*` scope for new internal packages.
+- Use public package entry points for cross-package calls. Do not depend on another package's `dist/` layout or bypass boundaries with deep source imports.
+- `packages/**` must not import `apps/**`. `packages/tui` must not depend on Agent, provider, session, or product code.
+- Put new vendor SDKs behind adapters in `packages/providers`. Coding-product integrations such as MCP and plugins belong in `packages/coding-agent`, not the generic Agent Loop or rendering library.
+
+## 3. Ownership of core concepts
+
+| Concept | Semantic owner | Product and host usage |
+| --- | --- | --- |
+| Agent Loop | `packages/agent-core/src/agent-loop.ts` | coding-agent composes it; TUI, print, JSON, RPC, and SDK reuse it. Do not create another loop. |
+| Session / transcript | Generic session contracts in agent-core; coding-agent's `AgentSession` / `SessionManager` own coding-session execution and persistence | UI holds input, connection, selection, and presentation state; it must not become the authority for persistent sessions. |
+| Context / compaction | Generic harness in agent-core; message conversion, skill retention, and recovery adapters in coding-agent | Presentation code must not assemble a second model context. Request projection must not rewrite the original transcript. |
+| Provider / model | Registration, catalogs, dialects, and adapters in providers | Products select and configure models. Dispatch by API dialect, never by provider name or display metadata. |
+| Tool / permission | Generic tool primitives in agent-core; coding tools, registration, permissions, and output retention in coding-agent | Clients present approval requests rather than duplicate permission decisions. Providers do not orchestrate tools. |
+| Subagent / workflow / goal / cron / plan / task | `packages/coding-agent/src/features/` | Compose through extensions and the same session lifecycle. Do not infer state from UI text or model replies. |
+| Configuration and resources | Neutral migrations in config; settings, trust, and resource resolution in coding-agent's core / step | CLI injects paths, defaults, and UI hooks. Step settings use `config.toml`; credentials, models, and sessions retain their own storage contracts. |
+| Theme / TUI | Product themes in coding-agent's `src/theme/`; rendering primitives in tui; interactive composition in `apps/cli/src/ui/` | Components consume the active theme. Do not add another theme registry or rendering loop. |
+| Host protocols | Independent in-process and wire contracts in contracts; concrete RPC / stdio protocols in existing mode entry points | Do not assume every mode already uses contracts. Adapt and validate new connections at host boundaries; keep concrete host objects out of contracts. |
+
+## 4. Choosing directories and implementing changes
+
+- Generic context, session, and tool primitives: `packages/agent-core/src/harness/`. Coding-product adapters: `packages/coding-agent/src/core/`.
+- Built-in product features and orchestration: `packages/coding-agent/src/features/`. Extension loading, registration, and hooks: `packages/coding-agent/src/core/extensions/`.
+- Step login, unified configuration, MCP, plugins, permissions, and feedback: `packages/coding-agent/src/step/`. Plugin manifests: `plugins/`.
+- CLI commands and startup: `apps/cli/src/commands/`, `args/`, `bootstrap/`, and `modes/`. Product UI: `apps/cli/src/ui/`.
+- Shell / bootstrap / modes enter UI only through `#ui` or `#ui/index`, never deep `#ui/...` imports. UI must not import the shell.
+- UI dependencies flow host → runtime → view. Runtime receives host capabilities through its own `RuntimeContext`; view must not import runtime. If used, `ui/state/` is a leaf and must not depend on host, runtime, or view.
+- Use existing actions and keybinding tables. Do not hardcode key matching in product logic.
+- Provide complete TypeScript types for public interfaces. Prefer `unknown` with validation over unnecessary `any`; verify external APIs against installed dependency types.
+- Relative TypeScript imports use `.ts` extensions and follow `check:ts-imports`. Source checked by the root configuration uses erasable syntax; do not add `enum`, parameter properties, or syntax requiring JavaScript emit.
+- Do not hand-edit `packages/providers/src/models.generated.ts` or provider data snapshots. Change generator scripts or inputs, then run the corresponding generation commands.
+- Preserve existing features and explicit user requirements. Do not delete functionality, weaken checks, or introduce unrelated refactors to make type or boundary checks pass.
+- Keep functions at one abstraction level; introduce helpers only when they own a meaningful operation, policy, or reusable behavior.
+- Validate external JSON, configuration, persisted data, and protocol inputs at their entry points. Narrow `unknown`; justify unavoidable `any` and type assertions rather than weaken checks or duplicate validation at every typed internal call.
+- Comments and JSDoc explain non-obvious behavior, failure, cancellation, and resource ownership; do not restate code or record an implementation conversation.
+- Handle failures at an explicit owner. Do not silently ignore invalid configuration, uncertain outcomes, or partially completed mutations. Best-effort catches must explain why ignoring the error is safe.
+- Cancellation and teardown must settle owned work, release resources, and prevent late callbacks from publishing into replaced sessions; requesting an abort alone does not prove cleanup completed.
+
+## 5. Development and validation
+
+- Use Node.js `>=22.19.0` and the pnpm version in the root manifest. Install with `pnpm install --ignore-scripts`; reproduce the locked environment with `pnpm install --frozen-lockfile --ignore-scripts`.
+- Pin direct external dependencies to exact versions. Update the lockfile with dependency changes; do not update dependencies for documentation tasks or bypass lockfile commit checks.
+- Run source through root `pnpm step` or `./step-test.sh`. `./step-test.sh --no-env` removes listed provider environment credentials, but local user resources still require care.
+- After code changes, run root `pnpm run check`, inspect the full output, and fix errors. It includes Biome autofixes, type checks, and boundary checks; it does not run tests.
+- Select tests for changed behavior using the [testing policy](docs/testing.md). Run Vitest from the owning package with `pnpm exec vitest --run <test-path>`; tui uses `node --test test/<name>.test.ts`.
+- Use `./test.sh` for repository tests and follow the pre-submission requirements in [CONTRIBUTING.md](CONTRIBUTING.md). It isolates user resources and credentials and builds offline if outputs are missing. Do not run a full Vitest suite that may activate real providers directly.
+- Unit and regression tests use faux providers, fixtures, mocks, and temporary directories. They must not read real accounts or consume paid model requests.
+- For documentation-only changes, verify relative links, directories, and commands and run `git diff --check`; follow the repository-wide pre-submission checks in `CONTRIBUTING.md`. Build only when a selected check needs artifacts; do not introduce real model calls for documentation validation.
+- When changing Agent Loop, sessions, tool permissions, providers, themes, or cross-process contracts, update the relevant `docs/`, package documentation, and affected `AGENTS.md` files.
+
+## 6. Task execution and Git collaboration
+
+- Before editing, read affected files, local rules, and relevant documentation. For complex or high-risk work, explain steps, tools, acceptance criteria, and rollback. Continue reversible work already authorized by the user.
+- For concurrent work, name module and file owners, agree shared interfaces first, and assign one integration owner. Coordinate edits to public types, exports, manifests, and the lockfile; hand off changed behavior, validation results, and remaining issues using the [collaboration workflow](docs/development.md#collaboration-workflow).
+- Prefer existing tools in `scripts/`. Keep temporary validation scripts in temporary directories, outside product source.
+- Do not commit or push unless requested. Stage only explicit paths belonging to the task; do not use `git add .` or `git add -A`.
+- If the working directory contains another task's changes, use a separate worktree or touch only your files. Do not stash, clean, or revert other contributors' changes.
+- Do not use `git reset --hard`, `git checkout .`, `git clean -fd`, skip hooks, or raw `--force`. Rewrite a published task branch only when explicitly requested; record its live remote OID, use an exact `--force-with-lease`, and abort on remote movement. If a Git operation conflicts with unrelated files, stop that operation and explain the conflict.
+- Write commit subjects and bodies, PR/MR titles and descriptions, public issues, and review comments in English. Commit and PR/MR titles follow Conventional Commits; split commits by coherent responsibility, not to inflate the history.
+- Commits, PR/MR descriptions, issues, and comments must not include AI-client attribution, bot co-authors, or generated-by footers. Keep author / committer as the current human contributor's Git identity.
+- Report the changes, validation evidence, and anything still unverified. Keep delivery notes concise and specific.
+
+## 7. Public source and support directories
+
+- Public source includes code, public tests, local builds, and CI checks. Private telemetry exporters, internal endpoints, release credentials, protected-tag operations, and upload/publication workflows stay in a separate release environment.
+- Do not copy internal execution records, private CI configuration, or infrastructure addresses into this repository. Follow the [public-source boundary](docs/open-source-status.md) and `check:public-boundary`.
+- Documentation: follow [docs/AGENTS.md](docs/AGENTS.md).
+- Check and build scripts: follow [scripts/AGENTS.md](scripts/AGENTS.md).
+- Local release packaging and installer templates: follow [infra/release/AGENTS.md](infra/release/AGENTS.md).
+- Built-in plugin manifests: follow [plugins/AGENTS.md](plugins/AGENTS.md).

CONTRIBUTING.md

@@ -44,6 +44,27 @@ If you ignore this document twice, or if you spam the tracker with agent-generat
 
 If you send a large volume of issues through automation, your GitHub account will be permanently blocked. No taksies backsies.
 
+## Commit and PR Conventions
+
+Write commit subjects and bodies, PR/MR titles and descriptions, public issues, and review comments in English. Commit and PR/MR titles follow Conventional Commits: `type(scope): summary`, with an optional scope. Use a concrete summary such as `fix(session): preserve queued input after cancellation`.
+
+Keep each commit focused on one coherent responsibility. Separate independent changes so reviewers can inspect them; do not add empty or artificial commits to increase the count. The author and committer remain the human contributor, as required by the attribution policy above.
+
+Follow the [development and collaboration guide](docs/development.md) for coding practices, concurrent ownership, error handling, and Git workflow. Use the [testing policy](docs/testing.md) to select behavior-level evidence while developing.
+
+## PR Review Checklist
+
+Use the [PR template](.github/pull_request_template.md) and replace its guidance with concrete evidence. Scale the description to the change, and explain any section that does not apply.
+
+- State the problem and resulting behavior. For bugs, include a reproducible trigger and explain the root cause.
+- Identify affected modules, public consumers, and changes to previously accepted inputs: configuration keys, environment variables, CLI arguments, provider responses, persisted sessions, RPC/SDK calls, and extension hooks.
+- For a changed default, removed fallback, or narrowed branch, describe who used the old behavior and their migration or escape path. A refactor accounts for the old path's feature inventory rather than silently losing it.
+- Treat system prompts, tool descriptions, reminders, and model-visible output as behavior. State who receives changed text, what it controls, and how the new behavior is verified.
+- Review public interfaces at both producer and consumer sides. Check old session data and error / cancellation behavior where relevant; document intentional compatibility changes.
+- Include exact validation commands and results, relevant platforms, and any skipped or unverified cases. Report pending CI as pending; a passing unit test alone does not prove a built CLI or protocol entry point works.
+- Explain user-visible snapshot changes and verify actual files, persisted state, or protocol output rather than only an agent's success message.
+- Confirm the diff contains only intended files, public examples use neutral data, and temporary handoff notes, private infrastructure, credentials, and AI attribution are absent.
+
 ## Before Submitting a PR
 
 Before submitting a PR:
@@ -55,6 +76,8 @@ npm run check
 
 Both must pass.
 
+These are repository-wide submission checks. During development, run focused checks for the changed behavior; do not repeat a passing check solely because a commit or push follows, unless files or relevant inputs changed. Inspect any modifications made by the formatter before staging or publishing.
+
 If you are adding a new provider to `packages/providers`, see `AGENTS.md` for required tests.
 
 ## Questions?