# Development

## Prerequisites

- [Task](https://taskfile.dev/) (task runner)
- Python 3.10+ (for linter, condensation tools)
- Bash (for install scripts, tests)

## Editing content

1. **Always edit in `.agent-src.uncondensed/`** — never in `dist/agent-src/` or `.augment/` directly
2. Run `task sync` to copy non-`.md` files
3. Use the `/condense` command to condense changed `.md` files
4. Run `task ci` to verify everything passes before pushing

---

## Task Commands

All commands use [Task](https://taskfile.dev/). The root `Taskfile.yml` orchestrates
`ci`/`_ci-*` and includes the four task groups under `taskfiles/`
(`ci-fast.yml`, `content.yml`, `engine.yml`, `release.yml`) with `flatten: true`,
so every task stays in the root namespace. Run `task --list` for the full list.

### CI & Verification

```bash
task ci                        # Run ALL CI checks locally (must pass before push)
task consistency               # Verify sync + generated tool outputs are clean
task consistency-fix           # Regenerate all derived outputs from source
```

### Sync & Condensation

```bash
task sync                      # .agent-src.uncondensed/ → dist/agent-src/, then project → .augment/
task sync-changed              # List .md files changed since last condensation
task sync-check                # Check if dist/agent-src/ is in sync (for CI)
task sync-check-hashes         # Verify condensed .md hashes match source
task sync-mark-done <file>     # Mark a single file as condensed
task sync-mark-all-done        # Mark ALL files as condensed
task sync-clean-hashes         # Remove stale hashes for deleted source files
```

### Tool Generation

```bash
task generate-tools            # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules, GEMINI.md
task clean-tools               # Remove all generated tool directories
```

### Testing

```bash
task test                      # Run all tests (bash + Python)
task test-install              # Install script integration tests
task test-python               # Condensation and linter tests
task test-linter               # Skill linter unit tests
task test-readme-linter        # README linter unit tests
task test-runtime              # Runtime registry + dispatcher tests
task test-tools                # Tool registry + adapter tests
task test-runtime-all          # All runtime and tools tests
```

#### CI test matrix

GitHub Actions runs the suite on every push and PR across:

| Runner | Python versions |
|---|---|
| `ubuntu-latest` | 3.10, 3.11, 3.12, 3.13 |
| `macos-latest` | 3.12 |

The matrix enforces the "Python 3.10+, stdlib only" guarantee from
`CONTRIBUTING.md`. Installer integration tests (`test_install.sh`,
`test_install_orchestrator.sh`) run on both Linux and macOS. Windows
is not part of the matrix — consumers on Windows use WSL2 (see
[installation guide](installation.md#windows)).

### Linting

```bash
task lint-skills               # Lint all skills, rules, and commands
task lint-skills-strict        # Lint with warnings as failures
task lint-skills-changed       # Lint only changed files
task lint-skills-report        # Per-file quality breakdown
task lint-skills-regression    # Compare against main branch (detect regressions)
task lint-skills-pairs         # Check condensation quality (source vs condensed)
task lint-readme               # Lint README.md
```

### Quality Checks

```bash
task check-condensation         # Verify code blocks, headings, frontmatter preserved
task check-refs                # No broken cross-references
task check-portability         # No project-specific references in shared files
task quality-report            # Per-artifact-type quality scores
```

### Runtime & Lifecycle

```bash
task runtime-list              # List all runtime-capable skills
task runtime-validate          # Validate runtime registry consistency
task runtime-e2e               # Dispatch each pilot skill (CI gate)
task tool-list                 # List all registered tools
task tool-validate             # Validate tool declarations
```

### Installation

```bash
task install -- --target <dir> # Run the installer orchestrator on a target
task install-hooks             # Install git hooks (pre-commit marketplace lint, pre-push sync check, chat-history bridges)
```

### Local dev install (no release)

Use these tasks to run the working tree as if it were a published
release — useful for testing changes before `task release` cuts an npm
version.

```bash
task dev:install-global        # Refresh ~/.claude, ~/.cursor, ~/.augment, … from this working tree (--force)
task dev:link                  # Symlink this repo as the global @event4u/agent-config (npm link)
task dev:unlink                # Remove the global symlink
```

**Switch the global install between dev and release** — one-shot toggles
that flip BOTH the `agent-config` bin on PATH and the user-scope content:

```bash
task install:use-dev           # global = THIS working tree (npm link + dev-build content)
task install:use-release       # global = latest npm release (npm i -g @latest + release content)
```

Run `install:use-dev` to test the working tree as the live global install,
then `install:use-release` to switch back to the published version. They are
symmetric — whichever you run last is the active global `agent-config`.

**Typical flow:**

1. In this repo: `task dev:link` — once. The `agent-config` bin on PATH
   now resolves into the working tree.
2. In this repo: `task dev:install-global` — every time you want
   user-scope content (`~/.claude/rules`, `~/.cursor/`, …) refreshed.
3. In a consumer project that uses `@event4u/agent-config` from npm,
   opt in to the linked dev tree:

   ```bash
   cd /path/to/consumer-project
   npm link @event4u/agent-config
   ```

   `npx @event4u/agent-config …` and `node_modules/.bin/agent-config`
   in that project now resolve into the dev tree. Undo with
   `npm unlink @event4u/agent-config` (project) and `task dev:unlink`
   (this repo).

**Caveat — npx outside a linked project:** `npx @event4u/agent-config`
in a directory without a linked `node_modules/@event4u/agent-config`
fetches the published version from the registry. Either run `npm link
@event4u/agent-config` in that project first, or call the global
`agent-config` bin directly (which `task dev:link` puts on PATH).

---

## Project Structure

```
.augment-plugin/               ← Plugin manifest (Augment CLI + Claude Code)
.claude-plugin/                ← Plugin manifest (Claude Code)
.github/plugin/                ← Plugin manifest (Copilot CLI)

scripts/
├── install                    ← Primary installer (orchestrator)
├── install.sh                 ← Payload sync stage (hybrid copy + symlink)
├── install.py                 ← Bridge files stage (.agent-settings.yml, JSONs)
├── postinstall.sh             ← npm postinstall hook → scripts/install
├── setup.sh                   ← One-time Composer hook setup
├── condense.py                ← Condensation hash management
├── check_condensation.py       ← Condensation quality checker
├── skill_linter.py            ← Skill/rule/command linter
├── lint_regression.py         ← Branch regression detection
├── generate_tools.sh          ← Generate tool-specific directories
├── check_references.py        ← Cross-reference validator
├── ci_summary.py              ← GitHub Actions job summary (dispatcher runs)
└── tools/
    ├── base_adapter.py        ← Tool adapter contract
    ├── github_adapter.py      ← GitHub API adapter
    └── jira_adapter.py        ← Jira API adapter

tests/
├── test_install.sh            ← install.sh payload-sync integration tests
├── test_install_orchestrator.sh ← scripts/install end-to-end tests
├── test_skill_linter.py       ← Linter unit tests
└── test_ci_summary.py         ← CI summary tests

.github/workflows/
├── skill-lint.yml             ← Lint + PR comment workflow
└── consistency.yml            ← Sync + hash + tool verification
src/templates/consumer-settings/   ← Settings templates for consumer projects

.agent-src.uncondensed/         ← Source of truth (human-readable, verbose)
├── rules/                     ← Behavior rules
├── skills/                    ← Skill definitions (SKILL.md per skill)
├── commands/                  ← Slash command definitions
├── guidelines/                ← Coding guidelines by language
├── templates/                 ← Document scaffolds
└── contexts/                  ← System knowledge documents

dist/agent-src/                    ← Condensed output (token-efficient, shipped)
├── (same structure)           ← Condensed .md + copied non-.md files

.augment/                      ← Local projection for Augment Code (gitignored)
├── rules/                     ← Real file copies (Augment cannot load symlinked rules)
└── skills/, commands/, ...    ← Symlinks → ../dist/agent-src/<sub>
```

---

← [Back to README](../README.md)
