ai-harness-setup

어떤 스킬인가요?

Build a step-by-step path from a plain repository to a full agent-driven engineering workflow. Inspects the repo first to detect the full tech stack, package managers, CI systems, and monorepo layout before making any changes. Then initializes APM, sets up spec-driven development (OpenSpec by default, or respects existing systems like SpecKit and BMAD), adds deterministic checks matched to the detected stack, installs applicable AI skills, creates workflow documentation, configures AI IDEs (Copilot, Cursor, Windsurf, Claude Code, OpenCode), and verifies the entire setup.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# AI Harness Setup

Use `ai-harness-setup` to bootstrap a repository for agent-driven engineering. The skill inspects the full tech stack first, then sets up APM, spec-driven development (OpenSpec by default, or the repo's existing system), deterministic checks with CI wiring, Dependabot, AI workflow and security skills, MCP servers matched to the stack, workflow documentation, and AI IDE configuration for every tool the team uses — finishing with a mandatory harness verification pass.

## Two Installation Options

You can install this skill with either `apm` or `npx skills`.

## Option 1: Install With APM

Use this option when you want the skill managed as a dependency and deployed to one or more supported targets.

### Prerequisites

- Install APM if needed: `curl -sSL https://aka.ms/apm-unix | sh`
- Verify APM: `apm --version`
- Initialize APM in the repo if needed: `apm init --yes`

### Install The Skill

```bash
apm install cisco-open/ai-harness-toolkit/skills/ai-harness-setup -t opencode -t cursor -t copilot -t claude -t windsurf
```

Notes:

- Adjust the `-t` targets to match the tools your team uses. Supported targets: `opencode`, `cursor`, `copilot`, `claude`, `windsurf`.
- For OpenCode only, `-t opencode` is enough.

### Verify The Install

```bash
apm deps list
apm deps tree
```

## Option 2: Install With `npx skills`

Use this option when you want to add the skill directly from the repository without managing it through APM.

```bash
npx skills add https://github.com/cisco-open/ai-harness-toolkit --skill ai-harness-setup
```

You can verify the CLI and installed skills with:

```bash
npx skills --version
npx skills list
```

## What The Skill Helps Set Up

1. **Stack detection** — inspects manifests, lockfiles, CI configs, and existing docs before making any changes
2. **APM** — skill and dependency delivery layer; initializes `apm.yml` and keeps the lockfile aligned
3. **Spec-driven development** — OpenSpec by default, or respects SpecKit, BMAD, or any existing system
4. **Deterministic checks** — type checking, linting, testing, security scanning, and build verification matched to the detected stack, with CI wiring for the detected CI system (for example, GitHub Actions, Jenkins, or GitLab CI)
5. **Dependabot** — automated dependency updates for each detected ecosystem
6. **AI tooling and skills** — workflow skills (PRs, review, reflection), security review rules, and stack-specific skills installed via APM; optional GitHub Agentic Workflows; MCP servers matched to the repo's stack
7. **Docs tree** — architecture, dev environment, validation, deployment, and workflow docs derived from the actual repo; `AGENTS.md` as a lean routing file; `CONTRIBUTING.md` updated to reference the docs
8. **AI IDE configuration** — Copilot, Cursor, Windsurf, Claude Code, and OpenCode surfaces configured for whichever tools the team uses
9. **Finalize APM state** — runs `apm install` to sync `apm_modules/`, lockfile, and all deployed files; commits `apm.yml`, `apm.lock.yaml`, and all deployed skill/prompt surfaces so every contributor gets agent context without running `apm install`
10. **Harness verification** — mandatory audit of the full changeset to close any gaps before finishing

## How To Invoke It

Different AI tools expose installed skills differently.

### GitHub Copilot Chat / Cursor / Claude Code / Windsurf

```text
/ai-harness-setup
```

### OpenCode

```text
Use the ai-harness-setup skill for this repository.
```

## Typical Outcomes

Depending on what the repository already contains, this skill may create or update:

- `apm.yml` and `apm.lock.yaml`
- GitHub Agentic Workflow files (`.github/workflows/`) when the team opts in
- `openspec/` (or documentation of the existing spec system)
- deterministic check configs and matching CI stages
- `.github/dependabot.yml`
- `.github/`, `.claude/`, `.opencode/`, `.cursor/`, or `.windsurf/` skill and prompt surfaces
- `docs/` tree with real content derived from the repo
- `AGENTS.md` and `CONTRIBUTING.md`

## Good Times To Use It

- When starting AI workflow adoption in an existing repo
- When bootstrapping a new repo for agent-assisted development
- When standardizing repo setup across multiple AI IDEs
- Before running an `ai-native-assessment`

# AI Tooling Bootstrap

Use this file when installing package-backed AI tooling with APM.

## Prerequisites

- Install APM with `curl -sSL https://aka.ms/apm-unix | sh` on macOS or Linux, or the matching Windows installer when needed.
- Run `apm --version` before modifying the repository.
- Use `npx skills find` only for broader discovery when repo-local and public curated sources do not already cover the need.

## Initialize APM

1. Inspect the repo for `apm.yml`, `apm.lock.yaml`, `apm_modules/`, and APM-managed skill directories.
2. If `apm.yml` is missing, run `apm init --yes` at the repo root.
3. Verify `apm_modules/` is in `.gitignore`.
4. If `apm.yml` already exists, read it before adding dependencies.

## Package Install Flow

1. Audit repo-local skills and existing APM deps before installing anything new.
2. Choose the matching package from the stack detection results in the main workflow.
3. Resolve the latest published tag for that package with `git ls-remote --tags https://github.com/cisco-open/ai-harness-toolkit "<name>-v*"` and install the newest matching tag.
4. Use the detected IDE targets in the install command and include protocol fallback:

```bash
apm install --target <ide-1> --target <ide-2> --allow-protocol-fallback cisco-open/ai-harness-toolkit/packages/<name>#<name>-v<latest>
```

5. Do not install `core` separately when a `stack-*` package already pulls it transitively.
6. If no package matches the detected stack, install `core` explicitly and layer dynamic stack-specific skills on top.

Use the matching package as the default baseline when one exists. After that, keep the dynamic path available for repo-specific gaps instead of treating the package as the complete install plan.

## Dynamic Fallback

- Even when a matching `stack-*` package exists, dynamic installs are still valid for repo-specific gaps that the package does not cover.
- Browse repo-local and public curated sources first for skills that match the detected stack.
- Use `npx skills find <query>` only as a search mechanism when a needed skill is not already available through repo-local or public curated sources.
- Install only the dynamic skills that match the detected stack or framework gap.

Typical order:
1. install the matching package for the detected stack when one exists
2. inspect what that package already deployed
3. add only the extra dynamic skills needed for uncovered framework, testing, review, or AI-runtime gaps
4. add extra MCP servers based on the detected stack
5. run `apm install` so the manifest, lockfile, deployed files, and MCP wiring stay in sync

## What To Commit

- Commit `apm.yml`, `apm.lock.yaml`, and all deployed files in `.github/`, `.claude/`, and `.opencode/` that APM materializes.
- Keep `apm_modules/` in `.gitignore`.
- After any install, run `apm install` if needed so deployed files and the lockfile stay in sync before committing.

## CI Drift Check

To catch cases where `apm.yml` changes without re-running `apm install`, add a CI step that verifies deployed files are in sync:

```bash
apm install
PATHS=".github/"
if [ -d ".claude/" ]; then
  PATHS="$PATHS .claude/"
fi
if [ -d ".opencode/" ]; then
  PATHS="$PATHS .opencode/"
fi
if [ -n "$(git status --porcelain -- $PATHS)" ]; then
  echo "APM deployed files are out of date. Run 'apm install' and commit the changes."
  git status --porcelain -- $PATHS
  exit 1
fi
```

## Verify

- `apm.yml` includes the expected package and any extra dynamic installs.
- `apm.lock.yaml` is present when installs succeeded.
- Deployed files in `.github/`, `.claude/`, and `.opencode/` are committed alongside `apm.yml` and `apm.lock.yaml`.
- `apm_modules/` is in `.gitignore`.

# CI Wiring Patterns

Use this file when wiring deterministic checks into the repo's CI system. Detect the CI system during the repo inspection phase (step 1 of the main workflow) and use the matching pattern below.

## Principle

Every deterministic check that runs locally should have a corresponding CI stage, step, or job. CI should enforce the same checks as local development -- no more, no less.

Choose one enforcement mode before wiring CI:

- `enforced`: deterministic checks fail the pipeline on findings
- `advisory`: deterministic checks still run and surface output, but CI remains green or unstable rather than failed

## Detecting the CI System

Look for:

- `Jenkinsfile` or `Jenkinsfile.*` -> Jenkins
- `.github/workflows/*.yml` -> GitHub Actions
- `.gitlab-ci.yml` -> GitLab CI
- `Dockerfile` or `docker-compose.yml` -> containerized builds (may layer on top of any CI)

If the repo uses a CI system not covered here, follow the same principles: match local checks 1:1 with CI stages, reuse existing scripts, and document any gaps.

## Jenkins Patterns

### Detecting Existing Structure

Before adding stages, understand the existing Jenkinsfile:

- Is it declarative (`pipeline { ... }`) or scripted (`node { ... }`)?
- Does it use shared libraries (`@Library('...')`)? If so, check which functions are already available.
- Does it have an existing validation, quality, or check stage?
- Does it call existing scripts (e.g., `make ci-check`, `./scripts/ci.sh`)?

### Adding Checks to a Declarative Pipeline

Add a new stage for deterministic checks, or append to an existing validation stage:

```groovy
stage('Deterministic Checks') {
    steps {
        // Lint
        sh '{lint_command}'

        // Type check
        sh '{type_check_command}'

        // Tests
        sh '{test_command}'

        // Security scanning
        sh '{sast_command}'

        // Dependency audit
        sh '{audit_command}'

        // Build verification
        sh '{build_command}'
    }
}
```

Replace `{lint_command}`, `{type_check_command}`, etc. with the actual commands from the stack-specific deterministic scans reference, using the detected package manager.

### Advisory Mode in Jenkins

When advisory mode is selected, wrap each deterministic check so the build stays successful while the stage is marked unstable:

```groovy
stage('Deterministic Checks') {
    steps {
        catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') {
            sh '{lint_command}'
        }
        catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') {
            sh '{type_check_command}'
        }
        catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') {
            sh '{test_command}'
        }
        catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') {
            sh '{sast_command}'
        }
        catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') {
            sh '{audit_command}'
        }
        catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') {
            sh '{build_command}'
        }
    }
}
```

Remove the `catchError(...)` wrappers when the repo upgrades to enforced mode.

### When to Add a New Stage vs. Modify an Existing One

- If the Jenkinsfile already has a `Quality` or `Validation` stage, **add the missing checks to it** rather than creating a parallel stage.
- If the Jenkinsfile uses shared library functions for checks, **call the existing functions** and only add new stages for checks not covered by the shared library.
- If the Jenkinsfile has no validation stage, **add a new `Deterministic Checks` stage** before the deploy or publish stage.

### Monorepo Jenkins Patterns

For monorepos with selective change detection:

```groovy
stage('Detect Changes') {
    steps {
        script {
            def changed = sh(script: './scripts/detect_changes.sh', returnStdout: true).trim()
            env.CHANGED_PACKAGES = changed
        }
    }
}

stage('Validate Changed Packages') {
    when { expression { env.CHANGED_PACKAGES != '' } }
    steps {
        sh "{run_checks_for_changed_packages}"
    }
}
```

## GitHub Actions Patterns

### Adding Checks to an Existing Workflow

Add a job or steps to the existing PR validation workflow (typically `.github/workflows/ci.yml` or `.github/workflows/pull-request.yml`):

```yaml
jobs:
  deterministic-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup environment
        # Use the appropriate setup action for the detected stack
        # e.g., actions/setup-node, actions/setup-python, actions/setup-java

      - name: Install dependencies
        run: {install_command}

      - name: Lint
        run: {lint_command}

      - name: Type check
        run: {type_check_command}

      - name: Tests
        run: {test_command}

      - name: Security scan
        run: {sast_command}

      - name: Dependency audit
        run: {audit_command}

      - name: Build verification
        run: {build_command}
```

### Advisory Mode in GitHub Actions

When advisory mode is selected, add `continue-on-error: true` to each deterministic check step:

```yaml
jobs:
  deterministic-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: {install_command}

      - name: Lint
        continue-on-error: true
        run: {lint_command}

      - name: Type check
        continue-on-error: true
        run: {type_check_command}

      - name: Tests
        continue-on-error: true
        run: {test_command}

      - name: Security scan
        continue-on-error: true
        run: {sast_command}

      - name: Dependency audit
        continue-on-error: true
        run: {audit_command}

      - name: Build verification
        continue-on-error: true
        run: {build_command}
```

Remove `continue-on-error: true` when the repo upgrades to enforced mode.

### When to Add a New Job vs. Add Steps

- If the workflow already has a `test` or `ci` job, **add missing checks as new steps** within that job.
- If the workflow separates concerns (lint job, test job, build job), **add each check to the appropriate existing job**.
- If no validation workflow exists, **create a new workflow file**.

### Monorepo GitHub Actions Patterns

Use path filters or change detection to run checks only for affected packages:

```yaml
on:
  pull_request:
    paths:
      - 'packages/my-package/**'
```

Or use a matrix strategy with a change detection step.

## General Wiring Rules

- **Reuse existing scripts.** If the repo has `make ci-check`, `./scripts/validate.sh`, or equivalent, call those from CI rather than duplicating individual commands.
- **Match local commands exactly.** CI should run the same commands that developers run locally. If local validation uses `make check`, CI should use `make check`.
- **Keep enforcement mode consistent.** If local commands or hooks are advisory, CI should also be advisory until the repo is intentionally tightened.
- **Document gaps explicitly.** If a check cannot be wired into CI immediately (e.g., missing credentials for a scanning tool), document it as a follow-up item rather than silently omitting it.
- **Keep CI config minimal.** Prefer calling a single validation script from CI over listing every check command inline. This ensures local and CI stay in sync.

# Dependabot Configuration

Use this file when adding Dependabot automated dependency update configuration to a repository.

## Guard-rails

- If `.github/dependabot.yml` or `.github/dependabot.yaml` already exists, do **not** create a duplicate. Leave the existing file untouched.
- Do **not** install, build, or execute any dependencies during this step.

## Creating the Configuration

If no Dependabot config exists, create `.github/dependabot.yml` based on the tech-stack ecosystems detected in Step 1. Map each detected package manager or manifest to the corresponding Dependabot `package-ecosystem` value:

| Detected tool / manifest | `package-ecosystem` value |
|---|---|
| npm, pnpm, yarn, bun (`package.json`) | `npm` |
| pip, pip-tools (`requirements.txt`, `setup.py`) | `pip` |
| poetry, uv (`pyproject.toml` with `[tool.poetry]` or `[project]`) | `pip` |
| Maven (`pom.xml`) | `maven` |
| Gradle (`build.gradle`, `build.gradle.kts`) | `gradle` |
| Docker (`Dockerfile`) | `docker` |
| GitHub Actions (`.github/workflows/`) | `github-actions` |
| Go modules (`go.mod`) | `gomod` |
| Cargo (`Cargo.toml`) | `cargo` |
| NuGet (`.csproj`, `packages.config`) | `nuget` |
| Composer (`composer.json`) | `composer` |
| Bundler (`Gemfile`) | `bundler` |
| Terraform (`.tf` files) | `terraform` |
| Hex (`mix.exs`) | `mix` |

Only include ecosystems actually detected in the repo. Do not add entries for stacks that are not present.

## Smallest Correct Configuration

Use the smallest correct configuration. A typical single-stack repo needs only:

```yaml
version: 2
updates:
  - package-ecosystem: "{ecosystem}"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
```

## Defaults

- `schedule.interval`: `"weekly"`
- `open-pull-requests-limit`: `5`
- Do **not** add `day`, `time`, `timezone`, `registries`, `target-branch`, `groups`, `ignore`, or `allow` unless the repository context explicitly requires them.

## Monorepo Handling

If the repo is a monorepo with workspace subdirectories that have their own manifests, add a separate `updates` entry for each subdirectory with the correct `directory` path. For example:

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/packages/frontend"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
  - package-ecosystem: "npm"
    directory: "/packages/backend"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
```

# Deterministic Checks Core

Use this file for the language-agnostic validation layer that should exist before stack-specific checks.

## Core Principle

Prefer repeatable commands that can run locally and in CI without human judgment.

## Progressive Enforcement

Before configuring deterministic checks, ask one binary question: do you want deterministic checks `enforced` or `advisory`?

- `enforced` keeps the current behavior: checks exit non-zero on failures and block commits or CI
- `advisory` keeps the same checks wired in, but they surface findings without blocking local workflows, hooks, or CI
- apply the chosen mode uniformly across all deterministic checks; do not mix enforced lint with advisory audit inside the harness defaults

This mode selection applies to local scripts, CI wiring, and git hooks together. The harness should install the full tooling surface either way. The only change is whether findings fail the workflow.

## Minimum Cross-Repo Baseline

Every repo should define a documented path for:

- dependency or vulnerability audit
- SAST or semantic security scanning
- tests
- build, package, or release verification
- one unified local validation command
- one CI path that mirrors the same checks

If the language supports linting or type checking, add those too, but keep this file focused on the baseline that applies across stacks.

## Wiring Rules

- prefer checked-in scripts, workspace tasks, or `make` targets over tribal-knowledge commands
- run the same checks locally before enforcing them in CI
- document tool installation when the check requires extra binaries
- keep the check names stable so future docs and skills can reference them reliably
- match every local check with a corresponding CI stage or step (see `references/ci-wiring.md` for patterns)

## Typical Shared Tools

- Semgrep or equivalent SAST
- dependency audit tooling
- CI workflow for pull-request validation
- git hooks when the repo uses them

## Local Validation Entry Path

Every repo should have a documented local validation entry path before deeper AI workflow automation is considered complete.

Set up the validation path in this order:

1. define the deterministic checks the repo must run before commit and push
2. expose them through one canonical command or task entry point
3. wire local hooks only after the commands pass reliably
4. make CI enforce the same core checks (see `references/ci-wiring.md`)

At minimum, the validation path should cover:

- linting when the stack supports it
- tests
- build or packaging verification
- security scanning or SAST
- dependency or vulnerability audit when practical

If the repo also uses git hooks, document which checks run at commit time versus push time.

## Monorepo Considerations

When the repo is a monorepo (detected in step 1 of the main workflow):

- determine whether checks should run at the workspace root, per-package, or both
- use workspace-aware commands when available (e.g., `pnpm nx affected`, `uv run` with workspace targeting, Gradle multi-project tasks)
- document the selective testing strategy if the repo has one (e.g., change detection scripts, `nx affected`, Gradle's changed-module detection)
- ensure coverage configuration accounts for multiple packages and their path mappings
- verify that build checks cover all packages, not just the root

## CI Wiring

Every deterministic check added locally should have a corresponding entry in the repo's CI system. See `references/ci-wiring.md` for concrete patterns for Jenkins and GitHub Actions.

Key principles:

- detect the CI system during the repo inspection phase (step 1)
- match local checks 1:1 with CI stages or steps
- reuse existing CI scripts and shared libraries when present
- keep the enforcement mode consistent between local commands, hooks, and CI steps
- document any checks that cannot be wired into CI immediately as explicit follow-up work

## Upgrade Path: Advisory to Enforced

Advisory mode is meant to help existing repos adopt the full check surface without blocking on day one. Upgrading to enforced mode should be a config-only change, not a rewiring project.

- JS/TS ESLint: change harness-added rules from `warn` back to `error`
- JS/TS hooks, audit, and Semgrep: remove the `|| true` suffixes from the generated commands
- Python ruff: remove `--exit-zero`
- Python bandit: remove `--exit-zero`
- Python audit and newly introduced type-checkers: remove `|| true`
- Java checkstyle: set `<failOnViolation>true</failOnViolation>`
- Java SpotBugs: set `<failOnError>true</failOnError>`
- Java OWASP dependency-check: lower `<failBuildOnCVSS>` from `11` to the repo's intended threshold
- GitHub Actions: remove `continue-on-error: true` from deterministic check steps
- Jenkins: remove `catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE')` wrappers around deterministic check stages

After flipping these settings, the same local entry point, CI stages, and hooks should remain in place; only their pass/fail behavior changes.

## Verification

- the repo has a documented deterministic validation path
- CI runs the same core checks as local development
- security scanning is not only advisory prose; it has an executable command
- local validation setup is documented and points to executable local checks
- the repo MUST have a single unified validation command that runs all deterministic checks in one invocation
- for monorepos: checks cover all packages appropriately (workspace-wide or per-package as needed)

# Deterministic Scans

Use repeatable local commands that can run in CI without human judgment.

## Cross-Stack Baseline

Every repo should have deterministic commands for:

- dependency or vulnerability audit
- static analysis or SAST
- linting
- type or compile validation when the language supports it
- tests
- build or packaging verification

Prefer repo-native entrypoints such as `pnpm` scripts, `make` targets, checked-in shell scripts, or the repo's primary build tool.

## Stack Guides

Read the per-stack scan guide that matches the repo:

- JavaScript and TypeScript: `references/stacks/javascript-typescript/deterministic-scans.md`
- Python: `references/stacks/python/deterministic-scans.md`
- Java: `references/stacks/java/deterministic-scans.md`

## Build-Gating Policy

Before wiring any new scan into CI, ask the user whether scans added by this skill should gate builds (fail the pipeline on findings) or run as advisory only (report findings without blocking). Apply the user's choice to all scans this skill adds. Either way, the repo's **pre-existing** checks must retain their current gating behavior -- do not weaken those.

## Wiring Rules

- expose the scans through one documented command path
- reuse existing scripts if the repo already has them
- add CI hooks only after the commands pass locally
- document any required tool bootstrap steps next to the commands that use them

# Docs Bootstrap

Use this file when creating the docs section that will explain the repo's actual engineering workflow.

## Goal

Create a docs tree that captures how this specific repository really works -- its architecture, services, data flow, deployment, validation, and agent workflow -- not a placeholder structure that promises details later. Every doc should contain real content derived from inspecting the repo.

## Research Before Writing

Before creating any doc, deeply research the repo to extract concrete material. Do not write docs from assumptions.

**What to investigate:**

- **Architecture**: Read source code structure, module boundaries, import graphs, package dependencies, and config files. Identify services, libraries, apps, workers, and their relationships. Map the data flow between components.
- **APIs and interfaces**: Find route definitions, API schemas (OpenAPI, GraphQL), RPC definitions, event handlers, message queues, and webhook endpoints. Document the actual endpoints, not just "the app has an API."
- **Configuration and environment**: Find environment variables, config files, feature flags, secrets references, and external service connections. Document what each service needs to run.
- **Data layer**: Find database configs, migration files, ORM models, schema definitions, cache configs, and storage integrations. Document the actual data model and storage strategy.
- **Deployment**: Find Dockerfiles, Helm charts, Kubernetes manifests, serverless configs, CI/CD deploy stages, and infrastructure-as-code. Document how the app gets from code to running in production.
- **Dependencies and integrations**: Find external service calls, SDK usage, third-party API clients, and MCP server connections. Document what the app depends on at runtime.
- **Testing strategy**: Find test directories, test configs, fixture patterns, mock strategies, and coverage configurations. Document how to run tests and what the testing philosophy is.
- **Scripts and automation**: Find helper scripts, Makefiles, task runner configs, and CLI tools. Document the available automation surface.
- **Tech debt**: While researching the repo, note patterns that indicate tech debt -- deprecated dependencies, TODO/FIXME/HACK comments, dead code, inconsistent patterns, missing tests for critical paths, outdated configs, and workarounds. Record these findings in `docs/tech-debt.md`.

## Seed Structure

```text
docs/
|- architecture/
|  |- overview.md                    - system architecture, component map, dependency flow
|  |- services.md                    - service descriptions, responsibilities, boundaries (if multi-service)
|  |- data-model.md                  - data layer, schemas, storage, migrations
|  `- integrations.md               - external services, APIs consumed, third-party dependencies
|- conventions/
|  |- coding-standards.md            - language conventions, style, patterns used in this repo
|  |- naming-and-structure.md        - directory layout, file naming, module organization
|  |- apm-management.md              - APM usage, installed skills, gitignore rules for managed paths
|  `- {task-runner}-usage.md         - task runner docs (e.g., nx-usage.md, makefile-usage.md, uv-usage.md)
|- dev-environment/
|  |- first-time-setup.md            - dependency bootstrap, toolchain install, env config
|  |- running-the-app.md             - local run commands for all services/apps
|  |- environment-variables.md       - required env vars, secrets, config files
|  `- common-issues.md              - known setup gotchas, platform-specific notes
|- deployment/
|  |- overview.md                    - how code gets to production
|  |- environments.md                - environment descriptions (dev, staging, prod)
|  `- infrastructure.md             - container, cloud, and infra config (if applicable)
|- validation/
|  |- local-validation-workflow.md   - deterministic review and validation path
|  |- ci-pipeline.md                 - CI parity with local checks
|  `- testing-strategy.md           - test organization, coverage, fixture patterns
|- security/
|  `- security.md                   - security expectations, scanning, audit procedures
|- tech-debt.md                      - known tech debt, deprecated patterns, improvement opportunities
`- workflow-overview.md              - top-level engineering workflow explainer
```

Adapt this structure to the repo. Not every repo needs every file:
- Single-service repos may not need `services.md`.
- Repos without a database may not need `data-model.md`.
- Repos that do not deploy (libraries, CLIs) may not need `deployment/`.

Add files when the repo has material that warrants them. Remove files when they would be empty filler.

Keep change proposals, specs, designs, and task breakdowns in OpenSpec artifacts under `openspec/changes/`, not under `docs/`.

## Authoring Order

Create or update these docs in roughly this order:

1. `docs/architecture/overview.md` - the system map: what this repo is, what it contains, how the parts relate
2. `docs/dev-environment/first-time-setup.md` - dependency bootstrap with real commands
3. `docs/dev-environment/running-the-app.md` - local run commands for every service/app/worker
4. `docs/dev-environment/environment-variables.md` - every env var, config file, and secret reference
5. `docs/architecture/services.md` - service descriptions with actual responsibilities (if multi-service)
6. `docs/architecture/data-model.md` - data layer, schemas, migrations (if applicable)
7. `docs/architecture/integrations.md` - external service dependencies and API clients
8. `docs/conventions/coding-standards.md` - observed patterns, not aspirational guidelines
9. `docs/conventions/apm-management.md` - APM usage, installed skills and their targets, and `.gitignore` rules for all APM-managed and OpenSpec-generated paths
10. `docs/conventions/{task-runner}-usage.md` - task runner docs with real commands
11. `docs/validation/local-validation-workflow.md` - deterministic review and validation path
12. `docs/validation/ci-pipeline.md` - CI parity with local checks
13. `docs/validation/testing-strategy.md` - test organization, how to run, coverage expectations
14. `docs/security/security.md` - security scanning, audit procedures, expectations
15. `docs/tech-debt.md` - known tech debt discovered during research (see below)
16. `docs/deployment/overview.md` - how the app ships (if applicable)
17. `docs/workflow-overview.md` - top-level explainer that links to all focused docs
18. `CONTRIBUTING.md` - contributor workflow entry points, referencing the docs above
19. `AGENTS.md` - lean routing file pointing agents to docs (see `references/templates/AGENTS.md`)

Write architecture and environment docs first because they require the deepest research and inform everything else. Write the workflow overview last because it synthesizes all other docs.

## What the Generated Docs Should Actually Contain

The goal is not just to scaffold folders. The generated documentation should describe the actual thing the repo does and the actual workflow contributors follow.

For each doc, prefer concrete material such as:

- the real bootstrap commands from lockfiles, package managers, toolchains, and helper scripts
- the real run commands for apps, workers, notebooks, CLIs, or services
- the real validation commands used locally and in CI
- the actual architecture boundaries, important directories, and dependency flow
- the actual API endpoints, data models, and integration points
- the actual deployment pipeline and environment configurations
- the actual agent touchpoints such as OpenSpec, OpenCode, vendored skills, slash commands, or automation entry points

If the repo uses OpenSpec, document that planning artifacts live in `openspec/changes/` and keep `docs/` focused on durable workflow and reference material.

Avoid vague filler like "run the app" or "follow team conventions" when the repo already exposes the exact commands and files. Every doc should contain information that could only come from actually reading this specific repo's code and config.

## `docs/conventions/apm-management.md` Content Guide

When the repo uses APM, create this doc to serve as the durable reference for how APM-managed dependencies interact with the repository. It should contain:

1. **Installed skills and their targets** -- list every skill installed via `apm install`, including which targets were used (e.g., `-t opencode -t cursor -t copilot -t claude`). Show the actual `apm install` commands used.
2. **Where APM materializes content** -- document the directories APM writes to for each target (e.g., `.github/skills/`, `.github/prompts/`, `.github/instructions/`, `.claude/skills/`).
3. **What to commit** -- explain that all deployed files in `.github/` and `.claude/` should be committed so every contributor gets agent context without running `apm install`. Only `apm_modules/` is gitignored.
4. **How to add a new skill** -- the `apm install` command pattern with targets, then stage and commit the deployed files alongside `apm.yml` and `apm.lock.yaml`.
5. **How to sync after pulling** -- `apm install` to regenerate managed content from `apm.yml` and `apm.lock.yaml`, then verify no drift with a conditional status check that only includes `.claude/` when present, for example:

   ```bash
   if [ -d .claude ]; then
     git status --porcelain .github/ .claude/
   else
     git status --porcelain .github/
   fi
   ```
6. **CI drift check** -- document the CI step that runs `apm install` and uses the same conditional `git status` pattern to fail if deployed files are out of sync (see `references/ai-tooling.md` for the pattern).
7. **Verification** -- `apm deps list`, `apm deps tree`, and confirming deployed files are committed.

This doc is the single source of truth for what APM manages in the repo. When a new skill is installed, this doc should be updated alongside the committed deployed files.

## `AGENTS.md` Purpose and Template

`AGENTS.md` is a **routing file**, not a documentation dump. It should be short and point agents to the right place in `docs/` for details.

Use `references/templates/AGENTS.md` as the starting point, then adapt the pointers to the target repo's actual docs structure. All substantive content belongs in `docs/`.

When creating `AGENTS.md`:
- **always include a repo map/directory structure** near the top of the file, showing the repo's actual layout as a tree (depth 2). This is the single most important section for agent navigation -- without it, agents cannot reliably locate files or understand the project's organization. Use the detection results from Step 1 to produce an accurate tree that covers source directories, config files, docs, scripts, and key entry points.
- explicitly state that non-trivial change planning belongs in OpenSpec
- point to the workflow overview and focused docs, not inline the content
- list the validation commands directly (these are short and agents need them immediately)
- do not duplicate content that lives in `docs/`

If `AGENTS.md` already exists, do not replace or discard its current content. Instead, merge in the `docs/` directory map alongside the existing material. Preserve any project-specific context, routing rules, or conventions the file already captures -- only add the pointers to the new docs tree.

Do not create parallel `docs/exec-plans/` or `docs/product-specs/` trees for work that should live in `openspec/changes/`.

## Synthesis Pass

After the focused docs are drafted:

1. create the top-level workflow overview (`docs/workflow-overview.md`) that links to all focused docs
2. verify every major statement is backed by a file, command, config, or directory in the repo
3. remove duplicate explanations that belong in a more focused page
4. add cross-links so a human or agent can move from setup to architecture to validation to deployment without guesswork
5. verify `AGENTS.md` points to the right docs and does not contain stale references
6. call out any genuinely missing documentation as follow-up work rather than hand-waving around it

## Content Rules

- keep durable rules in docs, not only in OpenSpec artifacts or chat transcripts
- use `AGENTS.md` as a routing file that points to `docs/`, not as a dump of every detail
- use `AGENTS.md` to point non-trivial change planning to OpenSpec
- keep stack-specific how-to material in focused docs under `docs/`
- make sure docs explain both the human entry point and the agent entry point
- prefer repo-specific filenames and titles over copying names from another workspace
- document real commands and observed repo behavior, not aspirational future state
- architecture docs should describe what the code actually does today, not what it might do someday
- log tech debt as you discover it during research -- do not fix it inline, document it in `docs/tech-debt.md` for follow-up

## Verification

- a new contributor can find setup, run, review, and OpenSpec planning entry points without tribal knowledge
- architecture docs accurately describe the repo's real structure, services, and data flow
- dev environment docs contain real commands that actually work
- validation and CI docs reference executable commands, not only policies
- the workflow overview links to all focused docs and reads as a coherent entry point
- `AGENTS.md` is a lean routing file that includes a repo map/directory structure and routes to `docs/`
- focused docs read like one coherent system after synthesis
- no doc is empty filler -- every file contains material derived from the actual repo

# GitHub Agentic Workflows

Use this file when the team wants GitHub Agentic Workflows enabled in the target repository.

Ask this question near the beginning of the setup flow, after initial repo inspection but before installing workflow tooling:

- Do you want to enable GitHub Agentic Workflows in this repository?

If the answer is no, skip this reference entirely.

## Goal

Provide a repeatable path for adding selected upstream `gh aw` workflows into the repository without requiring token values during the install step.

The first supported upstream workflow is:

- `https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-doc-updater.md`

## Install the `gh aw` Extension

First verify whether `gh aw` is already available:

```bash
gh aw version
```

If that fails because the extension is missing, install it:

```bash
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
```

Verify again:

```bash
gh aw version
```

If `gh aw` is already installed, prefer upgrading it before importing workflows:

```bash
gh extension upgrade aw
gh aw version
```

## Add a Supported Upstream Workflow

Use the upstream `add` path rather than copying workflow markdown manually.

For `daily-doc-updater`:

```bash
gh aw add https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-doc-updater.md
```

After the import finishes:

1. inspect `git status`
2. review all files created or modified by `gh aw`
3. keep generated workflow assets that belong to the imported workflow
4. confirm whether `.gitattributes` was added or updated with the generated lockfile rule

Do not hand-copy upstream workflow source files when `gh aw add` can generate them.

## Secrets and Token Setup

Complete the workflow import first, then document any required manual secret setup. This bootstrap flow should stop after adding the workflow files and documenting any manual follow-up.

### `COPILOT_GITHUB_TOKEN`

If using Copilot as your AI engine, set the GitHub Actions secret `COPILOT_GITHUB_TOKEN` to a GitHub Personal Access Token (PAT) so Copilot CLI can authenticate.

Reference:

- https://github.github.com/gh-aw/reference/auth/#copilot_github_token

Recommended setup:

1. Create a fine-grained PAT.
2. Verify the resource owner is your user account, not an organization.
3. Under `Permissions -> Account permissions`, set `Copilot Requests` to `Read`.
4. Generate the token and copy the value.
5. Add the PAT to the target repository's GitHub Actions secrets as `COPILOT_GITHUB_TOKEN`.

CLI example:

```bash
gh aw secrets set COPILOT_GITHUB_TOKEN --value "<your-github-pat>"
```

The GitHub UI can also be used if the operator prefers to add the secret manually.

Troubleshooting:

- If the workflow fails at the Copilot inference step even with the token set, verify that the token owner's account has an active Copilot license.
- Use the upstream auth reference above for additional diagnostics and setup details.

Do not ask the user to paste token values into tracked files, do not create pull requests as part of this bootstrap step, and do not configure credentials or repository secrets automatically.

## Scope Control

Keep the first change narrow.

- Start with the specifically requested upstream workflow
- Do not initialize the full `gh aw` repo surface unless the workflow requires it
- Do not add unrelated upstream workflows in the same change unless the user explicitly asks for them

## Files to Expect

The exact output can vary by `gh aw` version and workflow type, but verify the real generated files after import instead of assuming a fixed file set.

Common outcomes include:

- `.github/workflows/<workflow-name>.md`
- `.github/workflows/<workflow-name>.lock.yml`
- `.gitattributes`

Unless the user asks for broader initialization, avoid unrelated repo-wide `gh aw init` changes.

## Verification

- `gh aw version` succeeds
- the selected upstream workflow import command succeeds
- generated workflow files appear in `git status`
- any required secrets or token setup are documented as post-install follow-up
- no secret values were collected or written during bootstrap

# MCP Server Setup

Use this file when adding MCP servers to `apm.yml` as part of the harness setup. MCP servers give agents runtime access to external tools and services. Only add servers that match the repo's detected tech stack.

## Package-Provided Defaults

- `stack-frontend`, `stack-react`, and `stack-angular` already provide Chrome DevTools.
- Do not add those servers again as separate MCP installs when the matching package is already selected.
- Treat these package-provided MCP servers as the starting point. Add more MCP servers when the detected stack, infrastructure, or workflow still needs them.

## Detect Existing MCP Configurations

Before adding anything new, inspect the repo for MCP entries that already exist in tool-specific config files. Treat `apm.yml` as the single source of truth and migrate existing MCP declarations into `dependencies.mcp` instead of leaving them scattered across runtime-specific config files.

Common places to inspect:
- `opencode.jsonc`
- `.opencode/*.jsonc`
- `.cursor/`
- `.claude/settings.json`
- any checked-in agent or IDE config that contains `mcp`, `mcpServers`, or server definitions

When migrating existing entries:
1. Preserve the existing server definition.
2. Re-express it in `apm.yml` under `dependencies.mcp`.
3. Prefer a registry reference when the server exists in the APM registry.
4. Use `registry: false` when the existing server is private or not available in the registry.

## Discover Extra MCP Servers

For servers that are not already provided by a selected package, use `apm mcp search <term>` based on the detected stack.

Common search themes:
- `playwright`
- `postgres`
- `mysql`
- `sentry`
- `kubernetes`
- `terraform`
- `langgraph`
- `langchain`
- `ai`

Only add servers that provide clear value for the repo's actual workflow. Good examples include Playwright for browser automation, Postgres for database-heavy backends, or a public design-system server for UI repos.

Typical workflow:
1. account for any MCP servers already bundled by the selected package
2. migrate any repo-local MCP config into `apm.yml`
3. run `apm mcp search <term>` for the detected frameworks, databases, cloud providers, or AI runtimes that still need coverage
4. add only the extra servers that fill real workflow gaps

## Install and Guardrails

- MCP servers are declared under `dependencies.mcp` in `apm.yml` and installed through `apm install`.
- Use `apm install --only=mcp` when you need to sync only MCP servers.
- Use `apm install --dry-run` to preview what would be configured.
- Prefer `gh` over a GitHub MCP server for GitHub repo, issue, and pull request operations.
- Preserve existing MCP entries unless the user explicitly asks for cleanup.
- Do not bulk-add search results. Select only the MCP servers that match the repo's actual workflow.
- Document required environment variables for any self-defined server.

# OpenCode and ocx

Read this file when the repo contains `opencode.jsonc`, `.opencode/`, or the user explicitly wants OpenCode support.

When the repo also supports Cursor, GitHub Copilot, or Claude Code, install reusable skills with `apm install <package> -t opencode -t cursor -t copilot -t claude` and keep `.opencode/` focused on OpenCode-specific runtime config, plugins, commands, and `ocx` wiring.

## Files to Manage

- `.agents/skills/` - shared repo-local installed skills when the CLI materializes OpenCode, Cursor, and GitHub Copilot targets there
- `opencode.jsonc` - root OpenCode runtime config
- `.opencode/package.json` - dependencies for repo-local OpenCode plugins
- `.opencode/ocx.jsonc` - registry configuration for `ocx`
- `.opencode/worktree.jsonc` - worktree plugin sync and hook behavior
- `.opencode/plugin/` - repo-local plugin code
- `.opencode/command/` and `.opencode/commands/` - reusable command definitions

When APM is present, it also deploys installed skills to `.opencode/skills/` when the `.opencode/` directory exists. Treat that directory as APM-managed output and keep it aligned through `apm install`.

## Root Config Baseline

When establishing an OpenCode baseline, preserve existing config and merge in:

- plugin packages for DCP, plannotator, and subtask2
- provider or permission policies already established by the team

A baseline root `opencode.jsonc` should include:

- plugins:
  - `@tarquinen/opencode-dcp@latest`
  - `@plannotator/opencode@latest`
  - `@spoons-and-mirrors/subtask2@latest`
- `permission.task = deny`
- `disabled_providers = ["azure"]`

Never replace the entire file if the repo already has custom MCP entries, auth configuration, or provider restrictions.

## MCP Servers

MCP servers are declared centrally in `apm.yml` under `dependencies.mcp` and installed through `apm install`. See `references/mcp-servers.md` for the baseline defaults, stack-driven discovery workflow using `apm mcp search`, and APM dependency format.

Do not declare MCP servers directly in `opencode.jsonc`. Use `apm.yml` as the single source of truth so that APM handles wiring across all targets (OpenCode, Cursor, Copilot) and keeps configuration portable.

If the repo already has MCP entries in `opencode.jsonc` or `.opencode/` config files, migrate them into `apm.yml` `dependencies.mcp` during setup. See the "Detect Existing MCP Configurations" section in `references/mcp-servers.md` for the migration workflow.

## Local Plugin Baseline

When `.opencode/plugin/` exists:

- keep `.opencode/package.json` in sync with plugin imports
- run `bun install` in `.opencode/`
- do not assume root `package.json` dependencies satisfy `.opencode` plugins

Repo-local OpenCode plugins often depend on packages such as:

- `@opencode-ai/plugin`
- `jsonc-parser`
- `zod`
- `node-notifier`
- `detect-terminal`
- `unique-names-generator`

An `.opencode/` setup may also include:

- `.opencode/ocx.jsonc` with the `kdco` registry
- repo-local plugins in `.opencode/plugin/`
- command definitions in `.opencode/command/` and `.opencode/commands/`
- `.opencode/package.json` with `@opencode-ai/plugin` and helper deps

## ocx Baseline

If the repo uses `ocx`, ensure:

- `.opencode/ocx.jsonc` has the correct registry definitions
- `.opencode/worktree.jsonc` exists and matches the repo's worktree sync expectations
- contributors can run `ocx --version` and `bun install` inside `.opencode/`

## Verification

- `bun install` succeeds in `.opencode/`
- install commands for OpenCode, Cursor, GitHub Copilot, or Claude Code use the `--target` / `-t` flag (e.g., `-t opencode -t cursor -t copilot -t claude`)
- `.agents/skills/` contains the shared installed skills when the CLI materializes those selected targets there
- required plugin packages are present
- local plugin imports resolve
- JSONC files remain valid after editing
- OpenCode startup sees the intended plugin and MCP inventory
- MCP servers are declared in `apm.yml`, not in `opencode.jsonc`
- any pre-existing MCP entries from `opencode.jsonc` have been migrated to `apm.yml`

# OpenSpec Setup

Use this file first when the repo needs OpenSpec installed and wired into the engineering workflow.

## Goal

Make OpenSpec executable in the repo, not just described in prose. After setup, the repo should support:

1. `openspec init`
2. `openspec status`
3. change creation
4. artifact creation in dependency order
5. apply, verify, and archive flow
6. OpenCode commands or skills that expose the workflow ergonomically

## 1. Install the OpenSpec CLI

First verify whether `openspec` is already available:

```bash
openspec --version
```

If that fails, install the CLI globally before doing anything else:

```bash
npm install -g @fission-ai/openspec
```

OpenSpec is installed globally because it is a cross-repo workflow tool that should work regardless of the repo's language or package manager. A Python-only repo with no `package.json` still needs access to `openspec`.

After install, verify again:

```bash
openspec --version
```

## 2. Initialize the Repo

Once the CLI exists, initialize OpenSpec in the target repository. The `--tools` flag is required and specifies which AI tools the repo will use:

```bash
openspec init --tools opencode,claude,cursor,github-copilot,codex
```

The `--tools` flag accepts a comma-separated list. Choose the tools that match the team's actual usage. Common valid tool names include:

- `opencode`
- `claude`
- `cursor`
- `github-copilot`
- `codex`

Omit tools the team does not use. At minimum, include the tools the team is actively working with.

Then verify initialization:

```bash
openspec status --json
```

**Note:** On a freshly initialized repo with no change containers yet, `openspec status --json` may return `Error: No changes found` with a non-zero exit code. This is expected behavior, not a failure. To verify initialization succeeded, check that the following directories were created:

```bash
ls openspec/changes/ openspec/specs/
```

If both directories exist, initialization succeeded regardless of the `openspec status` output.

**Empty directory tracking:** Git does not track empty directories. If no initial change or spec exists yet, add `.gitkeep` files so the directory structure is committed:

```bash
touch openspec/changes/.gitkeep openspec/specs/.gitkeep
```

## 3. Add the OpenSpec Workflow Surface

OpenSpec is more useful when the repo exposes the workflow through local commands or skills.

For repos that expose OpenSpec through local commands or skills, add or verify these entry points:

- `/opsx-explore`
- `/opsx-new`
- `/opsx-continue`
- `/opsx-ff`
- `/opsx-apply`
- `/opsx-verify`
- `/opsx-archive`

In an OpenCode repo, these usually live in:

- `.opencode/command/opsx-*.md`
- `.opencode/skills/openspec-*/`

If the repo already vendors these, preserve and extend them rather than replacing them.

## 4. Verify the Expected Change Shape

Create or inspect one change container and confirm the workflow shape matches the repo's intended artifact chain.

Default artifact order:

```text
proposal -> specs/<capability>/spec.md -> design -> tasks
```

The repo should support change containers like:

```text
openspec/changes/<name>/
```

## 5. Document How the Repo Uses OpenSpec

Add durable pointers so contributors know when and how to use it:

- `CONTRIBUTING.md` should explain when OpenSpec is required and list the top-level commands
- `AGENTS.md` should point agents at the relevant workflow docs
- the repo's workflow doc should explain where OpenSpec fits in planning, implementation, and verification

## 6. Verification Checklist

- `openspec --version` succeeds
- `openspec init` has been run for the repo (check that `openspec/changes/` and `openspec/specs/` exist)
- OpenCode command or skill wrappers exist if the repo uses OpenCode
- non-trivial changes have a documented OpenSpec entry path

# Java Deterministic Scans

Use repeatable commands that can run locally and in CI without human judgment.

## Build Tool Resolution

Prefer the repo's existing build tool.

- use `pom.xml` when the repo is Maven-based
- use `build.gradle` or `build.gradle.kts` when the repo is Gradle-based
- for a fresh project in this workflow, default to Maven

## Required Plugins and Tools

For Maven-based repos, add or verify:

- `maven-compiler-plugin`
- `maven-surefire-plugin`
- `spotbugs-maven-plugin`
- `maven-checkstyle-plugin` or `maven-pmd-plugin`
- `dependency-check-maven`

For Gradle-based repos, wire equivalent plugins for compile, test, static analysis, and dependency scanning.

## Required Configuration

- pin the Java version in compiler config
- fail the build on static-analysis violations in enforced mode
- expose lint, test, and dependency scan through the repo's chosen build tool
- if SonarQube is used, wire the scanner in CI and keep local static-analysis commands deterministic

For Maven-based repositories, configure OWASP dependency-check to use the cached NVD data feed by default. An NVD API key is optional and must be supplied through the environment rather than committed to the repository:

```xml
<plugin>
  <groupId>org.owasp</groupId>
  <artifactId>dependency-check-maven</artifactId>
  <configuration>
    <nvdDatafeedUrl>https://dependency-check.github.io/DependencyCheck_Builder/nvd_cache/</nvdDatafeedUrl>
    <nvdApiKeyEnvironmentVariable>DEPENDENCY_CHECK_NVD_API_KEY</nvdApiKeyEnvironmentVariable>
  </configuration>
</plugin>
```

Before adding these elements, check the version of `dependency-check-maven` already pinned by the repository. If it does not support `nvdDatafeedUrl` or `nvdApiKeyEnvironmentVariable`, upgrade the plugin to a compatible release. When an upgrade is not possible, use the older plugin's supported `cveUrlBase` and `cveUrlModified` properties with a mirror that publishes the legacy NVD feed format, and verify the update logs show that the configured feed was used.

Treat `DEPENDENCY_CHECK_NVD_API_KEY` as an optional CI or developer environment variable, not a setup prerequisite. Keep the `nvdDatafeedUrl` configuration in both enforced and advisory modes. For Gradle-based repositories, use the OWASP plugin's equivalent data-feed configuration and the same environment-variable policy.

## Commands

- vulnerability audit: `mvn org.owasp:dependency-check-maven:check` or `./gradlew dependencyCheckAnalyze`
- SAST/static analysis: `mvn spotbugs:check` or `./gradlew spotbugsMain`
- lint/style: `mvn checkstyle:check` or `./gradlew checkstyleMain`
- tests: `mvn test` or `./gradlew test`
- build: `mvn verify` or `./gradlew build`

Choose one enforcement mode before wiring these commands:

- `enforced`: static analysis and audit failures should fail the build
- `advisory`: keep the same checks visible, but use tool-native settings so findings do not fail the build

## Advisory Mode Configuration

For Maven-based repos, use these settings in advisory mode:

- checkstyle: `<failOnViolation>false</failOnViolation>`
- SpotBugs: `<failOnError>false</failOnError>`
- OWASP dependency-check: `<failBuildOnCVSS>11</failBuildOnCVSS>`

Example Maven snippet:

```xml
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-checkstyle-plugin</artifactId>
  <configuration>
    <failOnViolation>false</failOnViolation>
  </configuration>
</plugin>
<plugin>
  <groupId>com.github.spotbugs</groupId>
  <artifactId>spotbugs-maven-plugin</artifactId>
  <configuration>
    <failOnError>false</failOnError>
  </configuration>
</plugin>
<plugin>
  <groupId>org.owasp</groupId>
  <artifactId>dependency-check-maven</artifactId>
  <configuration>
    <nvdDatafeedUrl>https://dependency-check.github.io/DependencyCheck_Builder/nvd_cache/</nvdDatafeedUrl>
    <nvdApiKeyEnvironmentVariable>DEPENDENCY_CHECK_NVD_API_KEY</nvdApiKeyEnvironmentVariable>
    <failBuildOnCVSS>11</failBuildOnCVSS>
  </configuration>
</plugin>
```

For Gradle-based repos, use the equivalent plugin settings that preserve scan output while keeping the build green.

## Wiring Rules

- keep one documented build-tool entrypoint for local and CI validation
- keep the chosen enforcement mode consistent across build config, hooks, and CI
- document any required plugin bootstrap in setup docs

# Spring Boot

Use this file when the repo contains Spring Boot dependencies, starters, or common Spring app structure.

## What to Install

Baseline packages and plugins usually include:

- Spring Boot starter dependencies needed by the app
- `maven-compiler-plugin` or Gradle Java plugin configuration
- `maven-surefire-plugin` or Gradle test task configuration
- `spotbugs-maven-plugin` or Gradle SpotBugs plugin
- `maven-checkstyle-plugin` or equivalent style plugin
- `dependency-check-maven` or Gradle OWASP dependency-check plugin

## Required Configuration

- pin Java version
- fail builds on static-analysis violations
- expose deterministic commands for test, build, dependency scanning, and static analysis
- document local runtime dependencies such as Java version and Maven or Gradle version

## Skills to Install

Focus this file on Spring Boot-specific additions instead of shared workflow tooling.

Install the `stack-spring-boot` package:

```bash
apm install --target <ide-1> --target <ide-2> --allow-protocol-fallback cisco-open/ai-harness-toolkit/packages/stack-spring-boot#stack-spring-boot-v<latest>
```

This package covers `java-springboot`, `spring-boot-testing`, `java-junit`, and the transitive `core` workflow bundle.

If the repo includes frontend or AI integrations, add those framework skills separately.

## Search Terms

Use curated sources first, then `npx skills find` for broader discovery when needed. Install the chosen package with `apm install`.

Useful queries include:

- `spring boot`
- `java backend`
- `security review`
- `performance`

## Framework Markers

- `org.springframework.boot`
- `spring-boot-starter-*`
- `src/main/java/.../Application.java`
- `application.yml` or `application.properties`

# Java

Read this file for Java services, CLIs, Spring applications, or mixed JVM repositories.

## Repo Markers

- `pom.xml`
- `build.gradle` or `build.gradle.kts`
- `settings.gradle` or `settings.gradle.kts`
- `src/main/java` or `src/test/java`

## Fresh Project Setup

For a fresh project in this workflow, use Maven unless the repo already uses Gradle.

Required plugins and tools for Maven-based repos:

- `maven-compiler-plugin`
- `maven-surefire-plugin`
- `spotbugs-maven-plugin`
- `maven-checkstyle-plugin` or `maven-pmd-plugin`
- `dependency-check-maven`

Required setup:

- pin the Java version in the compiler plugin
- fail the build on static-analysis violations
- expose commands for lint, test, build, and dependency scanning
- document local setup for Java and Maven or Gradle versions

## Skill Search Terms

Search for:

- `spring boot`
- `java backend`
- `spotbugs`
- `checkstyle`
- `security review`

## Skills to Install

Install these companion skills for Java code-review support:

```bash
apm install github/awesome-copilot/skills/security-review
apm install github/awesome-copilot/skills/java-refactoring-extract-method
apm install github/awesome-copilot/skills/refactor-method-complexity-reduce
```

These cover security review, method extraction refactoring, and complexity reduction.

## Recommended Deterministic Baseline

- `mvn test` or `./gradlew test`
- `mvn verify` or `./gradlew build`
- `mvn spotbugs:check` or `./gradlew spotbugsMain`
- `mvn checkstyle:check` or `./gradlew checkstyleMain`
- `mvn org.owasp:dependency-check-maven:check` or `./gradlew dependencyCheckAnalyze`

## Precommit Setup

For Java repos, prefer the build tool as the source of truth and wire hooks to that command surface.

Typical split:

- pre-commit: formatting or lightweight style checks if fast enough
- pre-push or explicit validation: full test, build, static-analysis, and dependency-check runs

## Extra Stack Discovery

Search for more stack signals such as:

- `spring-boot`, `quarkus`, `micronaut`, `junit`, `testcontainers`
- `.github/workflows/*.yml`, `Dockerfile`, `Jenkinsfile`
- multi-module build files and shared parent poms

## Framework-Specific References

- Use `references/stacks/java/framework-spring-boot.md` for Spring Boot repos.

# JavaScript and TypeScript Deterministic Scans

Use repeatable commands that can run locally and in CI without human judgment.

## Package Manager Resolution

Detect the package manager from the repo first. Do not assume a package manager -- use what the repo already has, then wire all scan commands through that tool.

Detection order:

- `packageManager` field in `package.json` -> use the specified manager
- `pnpm-workspace.yaml` or `pnpm-lock.yaml` -> use `pnpm`
- `bun.lockb` or `bun.lock` -> use `bun`
- `yarn.lock` -> use `yarn`
- `package-lock.json` -> use `npm`

Fresh project default when no existing manager is detected: `pnpm`

## Required Packages

- `typescript`
- `eslint`
- `@eslint/js`
- `typescript-eslint`
- `eslint-plugin-sonarjs`
- `eslint-plugin-unused-imports`
- `prettier`
- `husky`
- `lint-staged`
- test runner packages such as `vitest` or `jest`
- workspace tooling such as `nx` when the repo is an Nx workspace

## Required Configuration

- `tsconfig.json` or `tsconfig.base.json` should enable strict type checking
- `eslint.config.*` should include the repo's TypeScript, SonarJS, and unused-import rules
- for Nx repos, include `@nx/enforce-module-boundaries`
- wire `lint`, `type-check`, `test`, `build`, `audit`, and `semgrep` scripts or Nx targets

For fresh projects using `pnpm`, add `"packageManager": "pnpm@..."` to `package.json`. For other package managers, follow that manager's lockfile conventions.

## SonarJS Baseline From This Repo

Mirror these rule settings when building a repo like this one:

- `sonarjs/cognitive-complexity`: error at `15`
- `sonarjs/max-switch-cases`: error at `30`
- `sonarjs/no-commented-code`: warn
- `no-console`: error, allow `warn` and `error`
- `max-lines`: warn at `400`, skip blanks and comments
- `complexity`: warn at `15`
- `max-depth`: warn at `4`
- disable noisy overlap rules already covered elsewhere, such as duplicate-string and unused-import variants

## Required Commands

Substitute `{pm}` with the detected package manager (`pnpm`, `npm`, `bun`, or `yarn`).

For workspaces using Nx, prefer `{pm} nx affected -t <target>` over direct script calls.

Choose one enforcement mode before wiring these commands:

- `enforced`: use the commands below as blocking checks
- `advisory`: keep the same commands, but configure them to surface findings without failing

| Check | Nx workspace | Non-Nx |
|-------|-------------|--------|
| vulnerability audit | `{pm} audit --audit-level=high` | `{pm} audit --audit-level=high` |
| SAST | `{pm} semgrep` | `{pm} semgrep` |
| lint | `{pm} nx affected -t lint` | `{pm} lint` or `{pm} run lint` |
| type check | `{pm} nx affected -t type-check` | `{pm} exec tsc --noEmit` |
| tests | `{pm} nx affected -t test` | `{pm} test` or `{pm} run test` |
| build | `{pm} nx affected -t build` | `{pm} build` or `{pm} run build` |

## Advisory Mode Configuration

In advisory mode, keep the full check surface but make findings non-blocking:

- set harness-added ESLint rules to `warn` severity instead of `error`
- ensure the primary `lint` entrypoint also stays non-blocking by avoiding remaining error-severity harness rules, or suffix the generated lint command with `|| true` when the repo's tooling cannot express advisory behavior natively
- suffix Husky or lint-staged lint commands with `|| true`
- suffix audit commands with `|| true`
- suffix Semgrep commands with `|| true`
- apply the same rule to any generated type-check, test, or build command that the harness is newly introducing: if the underlying tool has no native advisory mode, use a consistent non-failing wrapper at the generated entrypoint

Examples:

```json
{
  "scripts": {
    "lint": "eslint . || true",
    "audit": "pnpm audit --audit-level=high || true",
    "semgrep": "semgrep scan . || true"
  }
}
```

```js
export default [
  {
    rules: {
      "sonarjs/cognitive-complexity": ["warn", 15],
      "no-console": ["warn", { allow: ["warn", "error"] }]
    }
  }
]
```

```sh
pnpm lint || true
pnpm exec tsc --noEmit || true
```

**Note on `bun`:** `bun` uses `bun run <script>` for package.json scripts and `bunx` instead of `npx`. The audit command may differ -- check `bun` docs for the current equivalent.

**Note on `npm`:** `npm` uses `npm run <script>` and `npx` for one-off executions. `npm audit` works the same as `pnpm audit`.

## Wiring Rules

- prefer repo-native entrypoints: package.json scripts, Nx targets, or workspace task runner commands
- use the detected package manager consistently across all commands
- expose one documented command path for contributors and CI
- keep the chosen enforcement mode consistent across scripts, hooks, and CI
- add CI hooks only after the commands pass locally

# Angular

Use this file when the repo contains `@angular/*`, `angular.json`, `nx g @nx/angular:*`, or other Angular workspace markers.

## What to Install

Baseline packages usually include:
- `typescript`
- `@angular/core`
- `@angular/cli`
- `typescript-eslint`
- Angular ESLint packages for lint integration
- test tooling used by the repo such as `jest`, `karma`, or `playwright`

## Required Configuration

- enable strict TypeScript mode
- enable Angular compiler strictness where applicable
- add deterministic lint, test, build, audit, and Semgrep commands
- keep workspace configuration checked in via `angular.json` or Nx project configuration

## Skills to Install

Focus this file on Angular-specific additions instead of shared workflow tooling.

Install the `stack-angular` package as the primary Angular companion:

```bash
apm install --target <ide-1> --target <ide-2> --allow-protocol-fallback cisco-open/ai-harness-toolkit/packages/stack-angular#stack-angular-v<latest>
```

This package covers `angular-developer`, `web-design-guidelines`, the transitive `stack-javascript-typescript`, and `core`, plus the Chrome DevTools MCP server.

Search for additional Angular-specific review or frontend testing skills in repo-local, public curated, and broader skills sources only when the package does not cover the repo's needs, then install the selected package with `apm install`.

Treat the package as the default baseline, then add only the dynamic Angular or frontend skills that close real repo-specific gaps.

## Search Terms

Browse curated sources first, then use `npx skills find` with queries such as:
- `angular review`
- `angular testing`
- `frontend testing`
- `security review`

## Framework Markers

- `@angular/core`
- `angular.json`
- `@angular/cli`
- `@nx/angular`

# React and Next.js

Use this file when the repo contains `react`, `react-dom`, `next`, `@vitejs/plugin-react`, or React-based Nx projects.

## What to Install

Baseline packages usually include:

- `typescript`
- `typescript-eslint`
- `eslint-plugin-react`
- `eslint-plugin-react-hooks`
- `eslint-plugin-jsx-a11y`
- `eslint-plugin-sonarjs`
- `@testing-library/react`
- `@testing-library/user-event`
- `vitest` or `jest`

For Next.js, also install the normal Next runtime and lint setup for that repo.

## Required Configuration

- enable TypeScript strict mode
- enable React, hooks, and accessibility lint rules
- include SonarJS rules for complexity and maintainability
- add deterministic test, build, and audit commands
- keep framework-specific runtime configuration checked in, such as `next.config.*` or `vite.config.*`

## Skills to Install

Install the `stack-react` package:

```bash
apm install --target <ide-1> --target <ide-2> --allow-protocol-fallback cisco-open/ai-harness-toolkit/packages/stack-react#stack-react-v<latest>
```

This package covers React best practices, `javascript-typescript-jest`, `webapp-testing`, `web-design-guidelines`, the transitive `stack-javascript-typescript`, and `core`, plus the Chrome DevTools MCP server.

Keep general workflow and security guidance in the shared setup docs; this file should stay focused on React-specific additions.

Treat the package as the default baseline, not the full ceiling. If the repo still has React- or Next-specific gaps after that install, add targeted dynamic skills on top.

## Install Order

1. audit local skills already vendored in the repo
2. install the `stack-react` package
3. add only extra dynamic skills when the repo has React-specific gaps the package does not cover
4. stop once the React-specific gaps are covered, then defer shared workflow installs to the common setup guidance

## Search Terms

Browse repo-local or other public curated sources first, then use `npx skills find` with queries such as:

- `react review`
- `react performance`
- `nextjs performance`
- `frontend testing`
- `accessibility review`

Install any selected extra package with `apm install <pkg>`.

## Framework Markers

- `react`
- `react-dom`
- `next`
- `@vitejs/plugin-react`
- `react-router-dom`
- `app/`, `pages/`, or `src/components/` patterns typical of React apps

# JavaScript and TypeScript

Read this file for Node.js, browser, React, Next.js, Vite, or Nx repositories.

## Repo Markers

Common markers:

- `package.json`
- `pnpm-workspace.yaml`, `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`
- `tsconfig.json`
- `nx.json`, `turbo.json`, `vite.config.*`, `next.config.*`

## Detection First

Before recommending or installing any tooling, detect what the repo already uses:

- **Package manager**: check for `packageManager` field in `package.json`, lockfiles (`pnpm-lock.yaml`, `bun.lockb`, `yarn.lock`, `package-lock.json`), or workspace config files. Use the detected manager for all commands.
- **Workspace tooling**: check for `nx.json`, `turbo.json`, `pnpm-workspace.yaml`, or Lerna config. Use workspace-aware commands when present.
- **Test runner**: check for `vitest.config.*`, `jest.config.*`, `playwright.config.*`, or test script definitions in `package.json`.
- **Monorepo layout**: check for workspace files, multiple `package.json` files, or project-level configs.

See `references/stacks/javascript-typescript/deterministic-scans.md` for detailed package manager detection order.

Fresh project default when no existing manager is detected: `pnpm`

## Skill Search Terms

Review repo-local and public curated skill inventories first, then use `npx skills find` (or `bunx skills find` for bun repos) only when broader discovery is still needed. Install selected skills with `apm install`.

Useful discovery queries include:

- `react review`
- `nextjs performance`
- `langgraph`
- `copilotkit`
- `nx workspace`
- `frontend testing`
- `security review`

Install only the skills that fill real gaps in the repo's current inventory.

## Skills to Install

Install the `stack-javascript-typescript` package as the default baseline for plain JavaScript/TypeScript repos:

```bash
apm install --target <ide-1> --target <ide-2> --allow-protocol-fallback cisco-open/ai-harness-toolkit/packages/stack-javascript-typescript#stack-javascript-typescript-v<latest>
```

This package provides the shared JavaScript/TypeScript baseline. After that install, add only the extra dynamic skills the repo still needs, such as framework-specific, AI-runtime, or review/testing coverage that is not already bundled.

Security review is still cross-cutting and applies to all TypeScript/JavaScript projects regardless of framework, whether it comes from the baseline package or an additional targeted install.

## Recommended Deterministic Baseline

- package install and lockfile check
- ESLint
- TypeScript type checking
- Vitest, Jest, Playwright, or the repo's chosen test runner
- Semgrep
- dependency audit
- build verification through the workspace task runner

## Fresh Project Setup

For a fresh project with no existing tooling, use `pnpm`.

Install the baseline packages:

```bash
pnpm add -D typescript eslint @eslint/js typescript-eslint eslint-plugin-sonarjs eslint-plugin-unused-imports prettier husky lint-staged semgrep
```

Add a test runner that matches the app type, such as `vitest`, `jest`, or `playwright`.

Required setup:

- add `"packageManager": "pnpm@<version>"` to `package.json`
- enable `"strict": true` in `tsconfig.json` or `tsconfig.base.json`
- create `eslint.config.*` with TypeScript, SonarJS, and unused-imports rules
- add scripts or Nx targets for `lint`, `type-check`, `test`, `build`, `audit`, and `semgrep`
- if the repo uses Nx, include `@nx/enforce-module-boundaries`

Use the SonarJS defaults documented in `references/stacks/javascript-typescript/deterministic-scans.md` when you want that lint posture.

For existing projects using `npm`, `bun`, or `yarn`, adapt the install command and script wiring to use that package manager instead. Do not switch the repo's package manager.

## Repo Patterns to Prefer

- wire scans through `package.json` scripts or workspace targets
- prefer `nx run`, `nx affected`, or equivalent workspace orchestration when present
- use the detected package manager consistently across all commands
- keep AI framework setup documented in `docs/dev-environment/` or `docs/conventions/`

## Local Validation and Hooks

For JavaScript and TypeScript repos, set up local validation through the workspace task runner and package scripts.

Recommended flow:

1. define canonical scripts or Nx targets for lint, type-check, test, build, audit, and Semgrep
2. document one canonical validation command or task entry point
3. wire git hooks with the package manager's normal tooling such as Husky or lefthook
4. keep staged-file autofix tasks small, but run affected-project validation for typecheck, tests, and build where possible

Typical hook split:

- commit-time hooks: ESLint, Prettier, lightweight staged-file validation
- push-time hooks: affected type-check, test, build, coverage, Semgrep, audit as appropriate

## Extra Stack Discovery

Search for more stack signals beyond top-level manifests:

- `next.config.*`, `vite.config.*`, `vitest.config.*`, `playwright.config.*`
- `electron*`, `tauri.conf.json`, `turbo.json`, `jest.config.*`
- dependencies such as `react`, `next`, `vite`, `electron`, `@langchain/*`, `@copilotkit/*`

## Framework-Specific References

- Use `references/stacks/javascript-typescript/framework-react.md` for React and Next.js repos.
- Use `references/stacks/javascript-typescript/framework-angular.md` for Angular repos.

# Python Deterministic Scans

Use repeatable commands that can run locally and in CI without human judgment.

## Package Manager Resolution

Detect the environment manager from the repo first. Do not assume a package manager -- use what the repo already has.

Detection order:

- `uv.lock` -> use `uv`
- `poetry.lock` -> use `poetry`
- `pyproject.toml` with `[tool.poetry]` -> use `poetry`
- `pyproject.toml` with `[tool.uv]` or `[build-system]` referencing `hatchling` or `setuptools` -> use `uv` or `pip` as appropriate
- checked-in `requirements.txt` or `requirements-dev.txt` -> use `pip`

Fresh project default when no existing manager is detected: `uv`

## Type Checker Resolution

Detect which type checker the repo already uses before recommending one.

Detection order:

- `pyrightconfig.json`, `pyrightconfig.jsonc`, or `[tool.pyright]` in `pyproject.toml` -> use `pyright`
- `[tool.basedpyright]` in `pyproject.toml` or basedpyright in dev dependencies -> use `basedpyright`
- `mypy.ini`, `.mypy.ini`, `setup.cfg` with `[mypy]`, or `[tool.mypy]` in `pyproject.toml` -> use `mypy`
- mypy in dev dependencies -> use `mypy`

If the repo already uses a type checker, use it. Do not recommend switching.

Fresh project default when no existing type checker is detected: `mypy`

Common type checker configurations:

- **mypy**: `disallow_untyped_defs = true` in `[tool.mypy]`
- **basedpyright**: `typeCheckingMode = "strict"` or baseline management in `[tool.basedpyright]`
- **pyright**: `typeCheckingMode = "strict"` in `pyrightconfig.json`

## Required Packages

Detect what is already installed. Only add packages that are missing.

Baseline packages (adjust tool names to match detected type checker and package manager):

- `ruff` (linter and formatter)
- type checker: `mypy`, `basedpyright`, or `pyright` (whichever the repo uses)
- `pytest` (test runner)
- `bandit` (SAST)
- `pip-audit` (vulnerability audit)
- `build` (packaging verification, when the repo produces packages)
- `pre-commit` (git hooks, when the repo uses them)

Example install for a fresh `uv` project using `mypy`:

```bash
uv add --dev ruff mypy pytest bandit pip-audit build pre-commit
```

Adapt the command for the detected package manager:

- **poetry**: `poetry add --group dev ruff mypy pytest bandit pip-audit build pre-commit`
- **pip**: `pip install ruff mypy pytest bandit pip-audit build pre-commit` (and add to `requirements-dev.txt`)

## Required Configuration

- keep tool configuration in `pyproject.toml` where possible
- configure the detected type checker with strict-ish settings appropriate to that tool
- define `tool.ruff` and `tool.pytest.ini_options` in `pyproject.toml`
- expose validation through the detected package manager's run command

## Commands

Substitute `{run}` with the appropriate command prefix for the detected package manager:

- **uv**: `uv run`
- **poetry**: `poetry run`
- **pip/venv**: use the virtualenv-activated command directly, or `python -m`

| Check | Command |
|-------|---------|
| vulnerability audit | `{run} pip-audit` |
| SAST | `{run} bandit -r .` |
| lint and format | `{run} ruff check .` |
| type check | `{run} mypy .` or `{run} basedpyright` or `{run} pyright` |
| tests | `{run} pytest` |
| packaging check | `{run} python -m build` |

Choose one enforcement mode before wiring these commands:

- `enforced`: use the commands above as blocking checks
- `advisory`: keep the same commands, but switch to native no-fail options where available

## Advisory Mode Configuration

In advisory mode, keep every deterministic check installed and wired, but make findings non-blocking:

- use `ruff check --exit-zero`
- use `bandit --exit-zero`
- suffix `pip-audit` with `|| true`
- if the harness is introducing a new type checker, suffix that command with `|| true` until the repo is ready to enforce it

Examples:

```bash
uv run ruff check . --exit-zero
uv run bandit -r . --exit-zero
uv run pip-audit || true
uv run mypy . || true
```

If the repo already had a type checker before the harness setup, keep using it as detected and decide whether to preserve existing enforcement rather than loosening it automatically.

## Wiring Rules

- keep one documented validation path
- use the detected package manager's run wrapper for local and CI consistency
- keep the chosen enforcement mode consistent across local commands, hooks, and CI
- add pre-push or CI hooks only after the commands pass locally
- for monorepos with uv workspaces, determine whether checks should run at the workspace root or per-package and document the approach

# Django

Use this file when the repo contains `django` in dependencies, `manage.py`, or Django-style project structure.

## What to Install

Baseline packages usually include:

- `django`
- `djangorestframework` (if building APIs)
- `pytest-django` for test integration
- `django-debug-toolbar` for local development
- `django-stubs` or `djangorestframework-stubs` for type checking

## Required Configuration

- configure `DJANGO_SETTINGS_MODULE` for test and lint environments
- enable strict type checking with Django stubs
- expose deterministic commands for lint, type check, test, migrations check, and build
- document local runtime dependencies such as Python version and database setup

## Skills to Install

Focus this file on Django-specific additions instead of shared workflow tooling.

Install the Django companion skills from Sentry's collection:

```bash
apm install getsentry/skills/skills/django-perf-review
apm install getsentry/skills/skills/django-access-review
```

These cover Django performance review (N+1 queries, queryset optimization) and access control review (permission checks, authentication).

## Search Terms

Use curated sources first, then `npx skills find` for broader discovery when needed. Install the chosen package with `apm install`.

Useful queries include:

- `django`
- `django rest framework`
- `django testing`
- `django security`

## Framework Markers

- `django` in dependencies (`pyproject.toml`, `requirements.txt`)
- `manage.py` in the project root
- `settings.py` or `DJANGO_SETTINGS_MODULE` references
- `from django` or `from rest_framework` in source files
- `urls.py`, `views.py`, `models.py` patterns

# FastAPI

Use this file when the repo contains `fastapi` in dependencies, `uvicorn` or `hypercorn` as the ASGI server, or FastAPI-style route patterns.

## What to Install

Baseline packages usually include:

- `fastapi`
- `uvicorn` or `hypercorn`
- `pydantic` (included with FastAPI)
- `httpx` for async test client
- `pytest` and `pytest-asyncio` for async test support

## Required Configuration

- enable strict Pydantic model validation
- configure async test support in pytest
- expose deterministic commands for lint, type check, test, and build
- document local runtime dependencies such as Python version and ASGI server

## Skills to Install

Focus this file on FastAPI-specific additions instead of shared workflow tooling.

Install the official FastAPI skill:

```bash
apm install fastapi/fastapi/skills/fastapi
```

If the repo includes frontend or AI integrations, add those framework skills separately.

## Search Terms

Use curated sources first, then `npx skills find` for broader discovery when needed. Install the chosen package with `apm install`.

Useful queries include:

- `fastapi`
- `pydantic`
- `async python`
- `api testing`

## Framework Markers

- `fastapi` in dependencies (`pyproject.toml`, `requirements.txt`)
- `from fastapi import` in source files
- `uvicorn` or `hypercorn` in dependencies or scripts
- `@app.get`, `@app.post`, `@router.get` patterns in source files

# Python

Read this file for Python service, CLI, agent, or notebook-heavy repos.

## Repo Markers

- `pyproject.toml`
- `requirements.txt`
- `poetry.lock` or `uv.lock`
- `pytest.ini`, `ruff.toml`, `mypy.ini`, `pyrightconfig.json`, or `[tool.basedpyright]` in `pyproject.toml`

## Detection First

Before recommending or installing any tooling, detect what the repo already uses:
- **Package manager**: check for `uv.lock`, `poetry.lock`, `[tool.poetry]`, `requirements.txt`. Use the detected manager for all commands.
- **Type checker**: check for `mypy.ini`, `.mypy.ini`, `[tool.mypy]`, `pyrightconfig.json`, `[tool.basedpyright]`, `[tool.pyright]`, or type checker packages in dependencies. Use the detected type checker. Do not recommend switching.
- **Linter**: check for `ruff.toml`, `[tool.ruff]`, `[tool.pylint]`, or linter packages in dependencies.
- **Test runner**: check for `pytest.ini`, `[tool.pytest.ini_options]`, `tox.ini`, `noxfile.py`.
- **Monorepo layout**: check for `uv.lock` with `[workspace]`, multiple `pyproject.toml` files, or workspace-level scripts.

See `references/stacks/python/deterministic-scans.md` for detailed detection resolution orders.

## Skill Search Terms

- `fastapi`
- `pydantic`
- `langchain python`
- `pytest`
- `security review`

## Skills to Install

Install the `stack-python-uv` package when the repo is managed with `uv`:

```bash
apm install --target <ide-1> --target <ide-2> --allow-protocol-fallback cisco-open/ai-harness-toolkit/packages/stack-python-uv#stack-python-uv-v<latest>
```

This package covers `security-review`, `python-best-practices`, and the transitive `core` workflow bundle. Repo-native tooling still handles linting, type checking, testing, and packaging.

After installing the matching package, keep the dynamic path available for repo-specific gaps such as framework, testing, or AI-runtime skills that are not already included.

For Poetry-, pip-, or other non-`uv`-managed repos, do not force `stack-python-uv`. Keep using the detected package manager for repo commands and install `core` plus only the extra Python-specific skills the repo still needs.

For extra Python-specific needs, browse repo-local and public curated skills first, then use `npx skills find` only when broader discovery is still needed. Install only the additional skills that fill real gaps in the repo's current workflow.

## Recommended Deterministic Baseline

Use the detected package manager's run command (`uv run`, `poetry run`, or direct invocation) for all of these:
- environment bootstrap command (detected: `uv sync`, `poetry install`, or `pip install -r requirements.txt`)
- lint with the detected linter (`ruff check .`, `pylint`, or the repo's existing lint command)
- type check with the detected type checker (`mypy .`, `basedpyright`, or `pyright`)
- tests with the detected runner (`pytest`, `tox`, `nox`, or the repo's existing test entrypoint)
- `bandit -r .`
- vulnerability audit with the detected package manager path (`pip-audit` or the repo's existing audit command)
- `python -m build` for package validation when applicable

## Fresh Project Setup

For a fresh project with no existing tooling, use `uv` as the package manager and `mypy` as the type checker.

Install the baseline packages:

```bash
uv add --dev ruff mypy pytest bandit pip-audit build pre-commit
```

Required setup:
- define tool settings in `pyproject.toml`
- expose checks through `uv run ...`
- configure `mypy` with stricter settings such as `disallow_untyped_defs = true`
- configure `ruff`, `pytest`, and optional coverage settings in `pyproject.toml`
- add `.pre-commit-config.yaml` if using git hook automation

For existing projects, adapt the above to the detected package manager and type checker.

## Documentation Placement

- environment bootstrap belongs in `docs/dev-environment/`
- durable coding and agent conventions belong in `docs/conventions/`

## Precommit Setup

For Python repos, prefer a documented validation command path plus optional git hooks.

Recommended flow:
1. install the repo's validation tools in its environment manager
2. add hook tooling only if the repo benefits from it, and keep the hook configuration minimal
3. keep slower checks like full `pytest`, type checking, or packaging validation available through the repo's main validation command and optionally push-time hooks
4. document the canonical validation command agents and contributors should run

Typical split:
- commit-time hooks: `ruff check .`, formatting, simple file hygiene
- push-time hooks or explicit validation: type checking, `pytest`, `bandit -r .`, `pip-audit`, `python -m build`

## Extra Stack Discovery

Search for more stack signals such as:
- `fastapi`, `django`, `flask`, `langchain`, `langgraph`, `pydantic`
- `Dockerfile`, `docker-compose.yml`, `.github/workflows/*.yml`
- task runners such as `tox.ini`, `noxfile.py`, `Makefile`
- monorepo markers such as uv workspace configuration, multiple `pyproject.toml` files

## Framework-Specific References

- Use `references/stacks/python/framework-fastapi.md` for FastAPI repos.
- Use `references/stacks/python/framework-django.md` for Django repos.

# AGENTS

This file is a routing map. Read the linked docs for details.

## Repo Map

<!-- REQUIRED: Generate this tree from the actual repo layout detected in Step 1. -->
<!-- Show depth 2. This section is critical for agent navigation. -->
<!-- Replace the example below with the real directory structure. -->

```text
├── src/                        - source code
│   ├── components/             - UI components
│   └── services/               - business logic
├── docs/                       - engineering docs (see links below)
│   ├── architecture/           - system design and data model
│   └── validation/             - deterministic checks and CI
├── openspec/                   - change proposals and specs
├── .github/                    - CI, skills, prompts, instructions
│   ├── workflows/              - CI/CD pipelines
│   └── skills/                 - agent skills
├── ...                         - (replace with real directories from the repo)
```

## Understand the System

- **Architecture**: `docs/architecture/overview.md`
- **Services and boundaries**: `docs/architecture/services.md`
- **Data model**: `docs/architecture/data-model.md`
- **External integrations**: `docs/architecture/integrations.md`

## Set Up and Run

- **First-time setup**: `docs/dev-environment/first-time-setup.md`
- **Run the app locally**: `docs/dev-environment/running-the-app.md`
- **Environment variables**: `docs/dev-environment/environment-variables.md`

## Validate Before PR

- **Local validation**: `docs/validation/local-validation-workflow.md`
- **CI pipeline**: `docs/validation/ci-pipeline.md`
- **Testing strategy**: `docs/validation/testing-strategy.md`

## Conventions

- **Coding standards**: `docs/conventions/coding-standards.md`
- **Task runner usage**: `docs/conventions/{task-runner}-usage.md`

## Workflow

- **Full workflow overview**: `docs/workflow-overview.md`
- **Contributing**: `CONTRIBUTING.md`
- **Security**: `docs/security/security.md`

## Tech Debt

- **Known tech debt**: `docs/tech-debt.md`
- When you encounter tech debt during any task (deprecated patterns, dead code, missing tests, workarounds, TODOs), log it in `docs/tech-debt.md` rather than fixing it inline. Keep entries actionable with file paths and brief descriptions.

## Change Planning

Use OpenSpec for non-trivial changes. Create proposals, specs, designs, and tasks under `openspec/changes/`. Do not create planning docs under `docs/`.

## Deployment

- **How we ship**: `docs/deployment/overview.md`

# Verify the Harness

Use this file to run the mandatory verification audit after steps 1-9 are complete and all changes have been staged or committed.

Its purpose is to audit every file the harness added or modified against the harness instructions themselves, catch anything the earlier steps missed or got wrong, and fix every gap before finishing.

## 1. Collect the changeset

Run `git status`, identify the branch point or initial commit from before the harness started as `<base>`, then collect the full changeset with `git diff --name-only <base>..HEAD` for committed changes and `git diff --name-only --cached` for staged but uncommitted changes. Combine and deduplicate those file lists so the changeset fully and reproducibly covers every file the harness created or modified. This changeset is the input for every check below.

## 2. Walk the harness steps against the changeset

Re-read steps 1-9 and the reference files they point to. For each step, verify the changeset satisfies the step's requirements. The checks below are organized by step.

**Step 1 — Repo inspection:**
- Verify the detection results were actually used by later steps (e.g., the detected package manager appears in scripts; the detected CI system received new stages; the detected test runner is referenced, not a different one).

**Step 1b — Preflight .gitignore:**
- Verify none of the harness-created paths (`docs/`, spec-driven development directories, `.opencode/`, `.github/skills/`, `.claude/`, `.cursor/`, `.windsurf/`, etc.) are gitignored. Run `git check-ignore` on every harness-created directory.

**Step 2 — APM:**
- `apm.yml` and `apm.lock.yaml` exist in the changeset.
- `apm_modules/` is in `.gitignore`.
- Deployed files in `.github/` and `.claude/` (if applicable) are in the changeset (not gitignored).

**Step 3 — Spec-driven development:**
- If an existing system was detected (SpecKit, BMAD, etc.), verify it was preserved and not overwritten by OpenSpec. Verify the existing system is documented in `CONTRIBUTING.md` and `AGENTS.md`.
- If OpenSpec was installed, verify `openspec/changes/` and `openspec/specs/` directories exist (with `.gitkeep` if empty), and that OpenCode commands or skill wrappers exist if the repo uses OpenCode.
- `CONTRIBUTING.md` and `AGENTS.md` reference whichever spec-driven development system the repo uses.

**Step 4 — Deterministic checks:**
- Identify the configured enforcement mode first (`enforced` or `advisory`) by inspecting the generated scripts, tool configs, CI steps, and hook commands.
- For every check category in the baseline (lint, type-check, test, build, security/SAST, dependency audit), verify:
  - A script, task, or command entry point exists in the repo (e.g., `package.json` script, Makefile target, Gradle task).
  - If the matching stack reference says a tool is REQUIRED (e.g., `eslint-plugin-unused-imports`, `eslint-plugin-sonarjs`, Husky, Semgrep), verify it is actually installed — present in `package.json` dependencies or the equivalent manifest, not just documented.
  - Config files for each tool exist (e.g., `eslint.config.*`, `tsconfig.json`, `ruff.toml`, `semgrep.yml`, or equivalent).
  - The config does not contradict other harness-generated files. For example, if a linter rule is mentioned as mandatory in `copilot-instructions.md` or `AGENTS.md`, the actual linter config must enable it.
- Apply the right pass criteria for the detected enforcement mode:
  - `enforced`: verify checks are configured to fail on findings or command failures.
  - `advisory`: verify checks are configured to run and surface output without blocking, using the documented no-fail flags or CI wrappers.
- **Dependency audit verification:** Verify that a dependency audit command exists as an executable script or task in the repo (e.g., `npm audit --audit-level=high`, `pnpm audit`, `pip-audit`, `mvn org.owasp:dependency-check-maven:check`), that it is included in the unified local validation command, and that it has a corresponding CI stage or step. A missing dependency audit command is a verification failure that must be fixed before the harness is considered complete.
- A unified local validation command exists (e.g., `npm run validate`, `make check`, `uv run validate`) and it covers lint, type-check, test, build, security scan, and audit.
- CI wiring: every local deterministic check has a corresponding stage or step in the CI config file. Open the CI config from the changeset and confirm 1:1 coverage.
- Git hooks: if the stack reference recommends hooks (e.g., Husky + lint-staged for JS/TS), verify the hook tooling is installed and configured, not just documented.
- Enforcement mode consistency: verify the same mode is expressed across local scripts, CI steps, and git hooks. For example, advisory-mode local scripts should not be paired with enforced CI stages or blocking hook commands.

**Step 5 — Dependabot configuration:**
- If `.github/dependabot.yml` or `.github/dependabot.yaml` already existed before the harness ran, verify no duplicate was created and the existing file was left untouched.
- If neither file existed, verify `.github/dependabot.yml` is now present in the changeset.
- Verify every `package-ecosystem` entry maps to a package manager or manifest actually detected in Step 1. No ecosystem entries should exist for stacks not present in the repo.
- Verify each entry uses `schedule.interval: "weekly"` and `open-pull-requests-limit: 5` unless the repository context explicitly required different values.
- Verify no unnecessary keys (`day`, `time`, `timezone`, `registries`, `target-branch`, `groups`, `ignore`, `allow`) are present unless the repository context explicitly required them.
- For monorepos, verify each workspace subdirectory with its own manifest has a separate `updates` entry with the correct `directory` path.

**Step 6 — AI tooling and skills:**
- `apm deps list` output matches the skills that should have been installed for the detected stack.
- No skills were installed that do not match the detected stack.
- Deployed skill files in `.github/`, `.claude/`, `.opencode/skills/` are present in the changeset.

**Step 7 — Documentation:**
- Cross-reference the seed structure from `references/docs-bootstrap.md` against the changeset. For every file the seed structure says should exist (given the repo's characteristics), verify it was created.
- Open each generated doc and verify:
  - It contains repo-specific content (real commands, real paths, real service names), not generic placeholders.
  - Commands and tool names are consistent with the detection results from step 1 (e.g., if the repo uses Vitest, no doc should reference Jest or Karma).
  - The unified validation command documented in `docs/validation/local-validation-workflow.md` matches the actual script in the manifest.
- `AGENTS.md` routes to `docs/`, includes a repo map/directory structure section near the top that is derived from the Step 1 detection results and rendered to depth 2, and does not inline content that belongs in focused docs.
- `CONTRIBUTING.md` references the docs tree, the spec-driven development workflow, and the validation command.

**Step 8 — AI IDE Configuration:**
- Verify at least GitHub Copilot (`.github/copilot-instructions.md`) is configured. Verify every other IDE the team uses also has config present in the changeset.
- For each configured IDE, verify the config covers all four required areas: (a) validation and build commands, (b) coding conventions and constraints, (c) routing to docs/specs/skills, (d) safety boundaries. If any area is missing, flag it.
- Verify all IDE configs are consistent with each other and with the docs from Step 7 — same tool names, same framework references, same test runner, same validation command, same safety boundaries.
- Verify workflow commands (spec-driven development commands, validation triggers, review commands) are registered in every configured IDE's command surface, not just one.
- If MCP servers were added (via APM), verify they match the detected stack. If no MCP servers are applicable, confirm none were added.
- If OpenCode is configured, verify `opencode.jsonc` contains the required plugin packages, permission rules, and that `.opencode/package.json` exists with resolvable dependencies. Verify JSONC files are syntactically valid.

**Step 9 — APM finalization:**
- `apm install` was the last APM command run (lockfile is up to date).
- All deployed files are staged/committed alongside `apm.yml` and `apm.lock.yaml`.
- CI drift check for APM is wired into the CI config.

## 3. Cross-file consistency check

Scan all generated and modified files for internal contradictions:
- The unified validation command must appear identically in: the manifest script, `docs/validation/local-validation-workflow.md`, `AGENTS.md`, `CONTRIBUTING.md`, and every AI IDE config file (`.github/copilot-instructions.md`, `.cursor/rules/`, `.windsurf/rules/`, `CLAUDE.md`, `opencode.jsonc` — whichever were created).
- Safety boundaries stated in one IDE config must not contradict those in another.
- Any tool listed as mandatory in one generated file must actually be installed and configured, not just mentioned.
- The enforcement mode must be internally consistent across tool configs, local validation scripts, CI steps, and git hooks. Advisory signals such as `--exit-zero`, `|| true`, `continue-on-error: true`, `catchError(...)`, or non-failing Maven plugin flags should either appear together or not at all, based on the chosen mode.

## 4. Fix gaps

For every gap or contradiction found in steps 2-3:
1. Fix it immediately — install the missing package, add the missing CI stage, correct the inconsistent reference, create the missing doc.
2. Log what was fixed.

## 5. Produce the verify report

After all fixes are applied, output a summary with these sections:

1. **Changeset stats** — number of files created, modified, and deleted.
2. **Per-step verification results** — for each step (1-9), state PASS or list what was fixed.
3. **Consistency check results** — any cross-file contradictions found and fixed.
4. **Unresolvable items** — anything that requires human action (secrets, permissions, access grants, large refactors) with the specific action needed.
5. **Final state** — the list of deterministic check commands available, the unified validation command, and the CI stages that mirror them.
6. **Enforcement mode** — whether the harness is configured as enforced or advisory, plus the specific signals that proved it during verification.

---
name: ai-harness-setup
description: Build a step-by-step path from a plain repository to a full agent-driven engineering workflow. Inspects the repo first to detect the full tech stack, package managers, CI systems, and monorepo layout before making any changes. Then initializes APM, sets up spec-driven development (OpenSpec by default, or respects existing systems like SpecKit and BMAD), adds deterministic checks matched to the detected stack, installs applicable AI skills, creates workflow documentation, configures AI IDEs (Copilot, Cursor, Windsurf, Claude Code, OpenCode), and verifies the entire setup.
compatibility: NodeJS, APM or permission to install it, and access to the target repository
metadata:
  version: "3.1"
---

# AI Harness Setup

Use this skill to bootstrap a repository toward a durable agent-driven workflow: deep inspection first, then APM as the dependency and skill delivery layer, spec-driven development for change management (OpenSpec by default, or the repo's existing system), deterministic checks matched to the detected stack, AI skills for review and delivery, a docs tree that explains the whole system, and AI IDE configuration for every IDE the team uses.

## Quick Start

1. **Inspect first.** Search the repo's manifests, lockfiles, CI configs, framework configs, and existing docs to classify the full stack before changing anything. Record: languages, package managers, type checkers, test runners, linters, CI system, monorepo layout, and existing tooling.
2. Read the matching stack guide based on detection results:
   - `references/stacks/javascript-typescript/stack.md`
   - `references/stacks/python/stack.md`
   - `references/stacks/java/stack.md`
3. If the repo uses a major framework, also read the matching framework guide:
   - `references/stacks/javascript-typescript/framework-react.md`
   - `references/stacks/javascript-typescript/framework-angular.md`
   - `references/stacks/java/framework-spring-boot.md`
4. Ask whether the team wants GitHub Agentic Workflows enabled in this repository.
5. Ask whether deterministic checks should be `enforced` or `advisory` before configuring any checks. Carry that answer through all downstream local scripts, CI wiring, and git hooks.
6. If GitHub Agentic Workflows are enabled, read `references/github-agentic-workflows.md` before installing AI workflow tooling.
7. Read `references/ai-tooling.md` before initializing APM or installing package-backed skills.
8. Read `references/mcp-servers.md` before adding extra MCP servers to `apm.yml`.
9. Read `references/openspec.md` for change management setup.
10. Read `references/deterministic-checks-core.md` and the matching per-stack `deterministic-scans.md` together -- they form one phase.
11. Read `references/dependabot.md` when adding Dependabot configuration.
12. Read `references/docs-bootstrap.md` when creating the docs section that explains the workflow.
13. Read `references/opencode.md` when OpenCode or `ocx` support is requested.
14. **Verify is mandatory.** After all setup steps finish, run the Verify step in Workflow Step 10 to audit the changeset against the harness instructions, fix every gap found, and produce a verify report. Never skip this step.

For non-trivial setup work, use subagents to split independent exploration or authoring tasks across stack, tooling, validation, and documentation domains, then merge the results in one final coordinating pass.

## Workflow

### 1. Inspect the Repo and Detect the Full Stack

Run this step before making any changes. The results drive every decision in later steps.

- Search manifests, lockfiles, CI configs, framework configs, dependency declarations, and existing docs.
- Do not stop at top-level markers. Search deeply for framework configs, nested package files, and CI pipeline definitions.
- Ask early whether the team wants GitHub Agentic Workflows enabled and whether deterministic checks should be enforced or advisory so the setup path can either include or skip that layer intentionally and wire checks correctly.
- **Detect and record:**
  - Languages and their versions
  - Package managers (npm, pnpm, bun, yarn, uv, poetry, pip, Maven, Gradle)
  - Type checkers already in use (TypeScript, mypy, basedpyright, pyright, pytype)
  - Linters already in use (ESLint, ruff, checkstyle, spotbugs)
  - Test runners (vitest, jest, pytest, junit, playwright)
  - Security scanners already present (bandit, Semgrep, npm audit, pip-audit, OWASP dependency-check)
  - CI system (Jenkins, GitHub Actions, GitLab CI) and its config files
  - Monorepo layout (uv workspaces, pnpm workspaces, Nx, Turborepo, Gradle multi-module, Maven multi-module)
  - Frameworks (React, Next.js, Angular, FastAPI, LangGraph, Spring Boot, etc.)
  - Existing docs, AGENTS.md, CONTRIBUTING.md
  - Existing skills, spec-driven development artifacts (OpenSpec `openspec/`, SpecKit `specify/` or `specs/`, BMAD, or other structured planning systems)
  - AI IDE configs already present: Cursor (`.cursor/`, `.cursorrules`), GitHub Copilot (`.github/copilot-instructions.md`, `.github/copilot-*`), Windsurf (`.windsurf/`, `.windsurfrules`), Claude Code (`.claude/`, `CLAUDE.md`), OpenCode (`opencode.jsonc`, `.opencode/`)
  - MCP surfaces and automation entry points
- Record all findings. This detection output drives steps 2-10.

**Monorepo detection:** If the repo is a monorepo (workspace files, multiple packages, shared build tooling), note the workspace layout, which packages have their own tooling configs, and whether checks should run at workspace level vs. per-package level. Adapt all later steps accordingly.

- Look for frameworks and tools such as React, Next.js, Vite, Electron, LangChain, LangGraph, CopilotKit, FastAPI, Hono, Axum, Tauri, Playwright, Docker, Jenkins, and GitHub Actions.
- When a framework is detected, load its framework-specific reference for use during the deterministic checks and skills phases.

### 1b. Preflight: Check `.gitignore` for Path Conflicts

Before creating any directories or files, verify that the paths this workflow will generate are not ignored by `.gitignore`:

```bash
git check-ignore docs/ openspec/ .opencode/ .opencode/skills/ .github/skills/ .github/prompts/ .github/instructions/ .github/agents/ .github/hooks/ .claude/ .claude/skills/
```

If any of these paths are listed in `.gitignore`, warn the user and resolve the conflict before proceeding. Content created under ignored paths will not appear in `git status` and will silently fail to commit.

**APM deployed files should be committed.** Files that APM places in `.github/` (prompts, skills, instructions, agents, hooks) and `.claude/` are intended to be version-controlled so that every contributor and Copilot on github.com gets agent context without running `apm install`. Only `apm_modules/` should be gitignored (APM handles this automatically).

To catch drift between `apm.yml` and deployed files, use a CI drift check rather than gitignore. See `references/ai-tooling.md` for the drift check pattern.

### 2. Initialize APM

- Treat APM as the dependency and delivery foundation for skills, prompts, and related agent packages.
- Detect whether the repo already has `apm.yml`, `apm.lock.yaml`, `apm_modules/`, or APM-managed `.github/skills/`, `.claude/skills/`, `.cursor/skills/`, or `.opencode/skills/` directories.
- If `apm.yml` does not exist, initialize it before installing skills:
  - run `apm --version`
  - run `apm init --yes` from the repo root
- If `apm.yml` already exists, inspect it before adding dependencies, then use `apm install` to sync the current dependency graph when needed.
- Verify `apm_modules/` is in `.gitignore` (`apm init` should add it automatically; if not, add it manually).
- Use imperative `apm install <package>` commands for skill installation so the manifest and lockfile stay aligned with the actual installed set.
- Use `references/ai-tooling.md` for initialization, install order, discovery strategy, and verification.

### 3. Set Up Spec-Driven Development

Ensure the repo has a spec-driven development system for managing non-trivial changes. Use the detection results from Step 1 to determine what already exists.

**If a spec-driven development system already exists** (SpecKit via `specify/` or `specs/`, BMAD, or any structured planning system with real artifacts):
- Respect it. DO NOT replace it with OpenSpec.
- Document the existing system in the docs tree (Step 7), `CONTRIBUTING.md`, and `AGENTS.md`.
- Wire its workflow commands into the AI IDE configs (Step 8) if it has a CLI or command surface.
- If the system has no CLI or command surface, document the manual workflow contributors should follow.

**If no spec-driven development system exists:**
- Install OpenSpec as the default.
- Use `references/openspec.md` for the install sequence, `openspec init`, command surfacing, and verification flow.
- Confirm `openspec/changes/` and `openspec/specs/` exist after initialization (with `.gitkeep` if empty).
- Add OpenSpec workflow commands to the AI IDE command surfaces (Step 8).

### 4. Add Deterministic Checks

Combine the language-agnostic baseline with stack-specific checks in a single pass, informed by the detection results from step 1.

Before configuring any deterministic checks, ask: "Do you want deterministic checks enforced or advisory?" Apply that one answer uniformly to all deterministic checks, CI steps, and git hooks that this workflow wires in.

**Language-agnostic baseline** (use `references/deterministic-checks-core.md`):
- dependency or vulnerability audit
- SAST or Semgrep-style scanning
- tests
- build or packaging verification
- CI parity with local commands

**Stack-specific checks** (use `references/deterministic-scans.md` as the overview, then the matching per-stack file):
- Read the core baseline first, then the stack-specific guide, then act once.
- Use the package manager, type checker, linter, and test runner **detected in step 1**. Do not override existing tooling with defaults.
- If the repo already has a tool fulfilling a check category (e.g., `basedpyright` for type checking), use it instead of recommending the default.
- Keep per-language commands and setup instructions in separate reference files instead of bloating the main workflow.

**Monorepo considerations:**
- Determine whether checks run at the workspace root or per-package.
- Use workspace-aware commands when available (e.g., `pnpm nx affected -t lint`, `uv run` with workspace targeting).
- Document selective testing strategy if the repo has one (e.g., change detection scripts).

**CI wiring:**
- Match every deterministic check added locally with a corresponding CI stage or step.
- Detect the CI system from step 1 and wire checks into the appropriate config format.
- For Jenkins repos, add checks as stages in the Jenkinsfile or as calls to existing shared library functions. See `references/ci-wiring.md` for patterns.
- For GitHub Actions repos, add checks as workflow steps.
- Reuse existing CI scripts if the repo already encodes the right invariant.

### 5. Add Dependabot Configuration

Ensure the repo has a Dependabot configuration for automated dependency updates based on the ecosystems detected in Step 1.

- Use `references/dependabot.md` for the guard-rails, ecosystem mapping, defaults, and monorepo handling.
- If `.github/dependabot.yml` or `.github/dependabot.yaml` already exists, leave it untouched.
- If neither exists, create `.github/dependabot.yml` with entries for each detected ecosystem.

### 6. Install AI Tooling and Skills

- Ask whether GitHub Agentic Workflows should be enabled before changing AI tooling.
- If the answer is yes, use `references/github-agentic-workflows.md` as the source of truth for `gh aw` installation, workflow import, generated files, and post-install token guidance.
- If the answer is no, skip `gh aw` setup entirely.

Use a package-first install flow. The curated APM packages are the default delivery path for skills and any MCP servers they already bundle.

- Start with `apm --version`.
- Audit repo-local skill directories and existing APM dependencies before installing duplicates.
- Initialize APM first if the repo does not already have `apm.yml`.
- Resolve the latest published package tag at install time. Use `git ls-remote --tags https://github.com/cisco-open/ai-harness-toolkit "<name>-v*"`, sort the returned tags by semver, and install the newest matching tag. Do not hardcode package versions in this skill.
- Use the detected IDE targets in every package install command and include protocol fallback:

```bash
apm install --target <ide-1> --target <ide-2> --allow-protocol-fallback cisco-open/ai-harness-toolkit/packages/<name>#<name>-v<latest>
```

- Choose the default package from the detection results in step 1:

| Detected stack | Install |
| --- | --- |
| JavaScript/TypeScript, no framework | `stack-javascript-typescript` |
| Vue, Svelte, or other generic web UI | `stack-frontend` |
| React or Next.js | `stack-react` |
| Angular | `stack-angular` |
| Python managed with `uv` | `stack-python-uv` |
| Java with Spring Boot | `stack-spring-boot` |
- Every `stack-*` package already pulls `core` transitively. Do not install `core` separately when a stack package matches.
- If no stack package matches (for example Go, Rust, plain Java, or another unpackaged backend), install `core` explicitly and then add only the extra dynamic skills that the detected stack still needs.
- Use `references/ai-tooling.md` for the install mechanics, what-to-commit rules, and dynamic fallback workflow.

**Dynamic fallback and add-ons:**
- Use the matching package as the default baseline when one exists, then add only the extra dynamic skills that cover real repo-specific gaps.
- Browse repo-local and public curated sources first for Cisco-curated skills that match the detected stack.
- Use `npx skills find <query>` only as a search mechanism when the needed skill is not already available through repo-local or public curated sources.
- If no package matches (for example FastAPI, Django, plain Java, Go, Rust, LangGraph, or CopilotKit), keep that part of the stack dynamic.

### 6b. Add MCP Servers

Add MCP servers to `apm.yml` based on the detected tech stack. MCP servers give agents runtime access to external tools and services.

- Read `references/mcp-servers.md` for the package-backed defaults, discovery workflow, and APM dependency format.
- Inspect the repo for existing MCP declarations in `opencode.jsonc`, `.opencode/`, Cursor, Claude, and similar config files, then migrate those definitions into `apm.yml` so APM becomes the single source of truth.
- Treat package-provided MCP servers as already handled by the corresponding package install:
  - `stack-frontend`, `stack-react`, and `stack-angular` provide Chrome DevTools.
- Treat those package-provided MCP servers as the baseline, not the ceiling. Add extra MCP servers when the detected stack still justifies them.
- Use `apm mcp search <term>` only for extra servers not covered by a package, such as Postgres, Playwright, Sentry, Kubernetes, or Terraform. Only add servers that provide clear value for the repo's actual workflow.
- All MCP servers are declared in the `dependencies.mcp` section of `apm.yml` and installed through `apm install`.
- Preserve any existing MCP entries in `apm.yml` and carry forward any repo-local MCP config that should remain supported.

### 7. Create the Docs Section That Explains the Workflow

**Synthesis checkpoint:** Before writing docs, consolidate all findings from steps 1-6. The docs must accurately reflect everything that was detected, installed, and configured.

- **Verify `docs/` is not gitignored.** Run `git check-ignore docs/` before creating any files. If `docs/` is ignored, update `.gitignore` first -- otherwise the entire docs tree will be invisible to git.
- **Research deeply before writing.** Read source code, configs, CI pipelines, deployment configs, data models, API definitions, and integration points. Every doc should contain material that could only come from actually reading this repo.
- Use `references/docs-bootstrap.md` for the full seed structure, research checklist, and authoring order.
- Create architecture docs first (system overview, services, data model, integrations) because they require the deepest research and inform everything else.
- Create dev environment docs with real commands (setup, run, env vars).
- Create validation docs that reference the deterministic checks wired in step 4.
- Create deployment docs if the repo ships to production.
- Write the workflow overview last -- it synthesizes all other docs.
- Create `AGENTS.md` as a **lean routing file** that points agents to `docs/`. Do not dump content into `AGENTS.md` that belongs in focused docs.
- Update `CONTRIBUTING.md` to reference the docs tree.
- Every doc must contain real content derived from the repo. No empty scaffolds or placeholder text.

### 8. Configure OpenCode and ocx When Present

- If the repo uses OpenCode, merge config instead of replacing it.
- Use `references/opencode.md` for the file-level config, plugin, command, and verification details.
- For repos that also use Cursor or GitHub Copilot, install reusable skills with `apm install <package> -t opencode -t cursor -t copilot` and let the CLI materialize the repo-local layout.
- Ensure the repo's OpenCode layer includes the required plugin packages and permission rules.
- Add MCP server entries only when they match the detected stack. See `references/mcp-servers.md` for the baseline and discovery workflow, and `references/opencode.md` for OpenCode-specific MCP config.

### 9. Finalize APM State and Commit Deployed Files

After all skills are installed and configuration is complete:

1. Run `apm install` to ensure `apm_modules/`, the lockfile, and all deployed files are fully in sync with `apm.yml`.
2. Verify `apm_modules/` is in `.gitignore`.
3. Stage and commit together:
   - `apm.yml`
   - `apm.lock.yaml`
   - All deployed files in `.github/` (skills, prompts, instructions, agents, hooks)
   - All deployed files in `.claude/` (if present)
   - All deployed files in `.opencode/skills/` (if present)
4. These files are version-controlled so every contributor and Copilot on github.com gets agent context without running `apm install`.

### 10. Verify the Harness

This step is mandatory. Run it only after steps 1-9 are complete and all changes have been staged or committed.

Use `references/verify-harness.md` for the full verification procedure. It covers:

1. Collecting the changeset (committed + staged files)
2. Walking each harness step (1-9) against the changeset to confirm requirements are satisfied
3. Cross-file consistency checks (validation commands, safety boundaries, tool names across all generated files)
4. Fixing gaps immediately rather than logging them as tech debt
5. Producing a structured verify report

## Guardrails

- **Never run deterministic checks.** This skill adds and configures deterministic commands (linters, type checkers, security audits, test runners, SAST tools, dependency audits, builds, scans, etc.) but must never execute them. Running these checks is the responsibility of the developer or CI pipeline, not this setup skill.
- **Detect before prescribing.** Always check what the repo already uses before recommending or installing tooling. Never override an existing tool with a default.
- Keep `apm.yml` and `apm.lock.yaml` aligned with the actual installed packages.
- Never overwrite existing secrets or credential files.
- Never remove user-defined plugin, skill, or MCP entries unless the user asked for cleanup.
- Prefer idempotent edits so the setup can be re-run safely.
- Prefer repo-local commands over globally assumed tooling.
- Document durable workflow rules in `docs/`, not only in the final chat response.
- When installing skills from external sources, install only those applicable to the repo. Do not bulk-install everything from a source.

## Reference Map

- `references/openspec.md` - step-by-step OpenSpec bootstrap
- `references/github-agentic-workflows.md` - optional `gh aw` bootstrap and workflow import guidance
- `references/deterministic-checks-core.md` - language-agnostic deterministic baseline
- `references/deterministic-scans.md` - cross-language deterministic scan overview
- `references/dependabot.md` - Dependabot configuration guard-rails, ecosystem mapping, and defaults
- `references/ai-tooling.md` - APM initialization, package install mechanics, and dynamic fallback workflow
- `references/mcp-servers.md` - package-provided MCP defaults, extra MCP discovery, and APM dependency format
- `references/opencode.md` - OpenCode and ocx config patterns
- `references/docs-bootstrap.md` - how to create the docs section
- `references/verify-harness.md` - full verification procedure for Step 10 (changeset audit, per-step checks, consistency, gap fixing, report)
- `references/ci-wiring.md` - CI integration patterns for Jenkins and GitHub Actions
- `references/stacks/javascript-typescript/stack.md` - JS/TS-specific setup
- `references/stacks/javascript-typescript/deterministic-scans.md` - JS/TS deterministic commands and wiring
- `references/stacks/javascript-typescript/framework-react.md` - React and Next.js setup plus the `stack-react` package
- `references/stacks/javascript-typescript/framework-angular.md` - Angular setup plus the `stack-angular` package
- `references/stacks/python/stack.md` - Python-specific setup plus the `stack-python-uv` package
- `references/stacks/python/deterministic-scans.md` - Python deterministic commands and wiring
- `references/stacks/java/stack.md` - Java-specific setup
- `references/stacks/java/deterministic-scans.md` - Java deterministic commands and wiring
- `references/stacks/java/framework-spring-boot.md` - Spring Boot setup plus the `stack-spring-boot` package