init-idd

# /init-idd Initialize IDD Stack for the current repository. Scans the codebase to detect language, framework, test runner, and repo size, then generates a `.idd.yml` config file with project-specific defaults. **Invocation**: `/init-idd` — interactive. `/init-idd --auto` (or `IDD_AUTO_MODE=1`) — no prompts; an existing `.idd.yml` is kept. ## When to Use - **Do** run this skill the first time a repository starts using IDD Stack, or when the existing `.idd.yml` is outdated after a stack migration. - **Do** treat it as idempotent for the "already exists" path — merge or overwrite based on user confirmation. - **Avoid** running it every session — it is a one-time setup skill. - **Never** modify or delete files outside the repo root, and never commit anything (leave that to the user). Inside it, write only `.idd.yml` and the repo's own `.gitignore` (*Ignore Rule*). **Context and token budget:** this skill stays small — it reads only a handful of files (`package.json`, `requirements.txt`, etc.) to keep the main agent's context window compact. ## Instructions 1. Verify prerequisites (git repo present). 2. Make `.gitignore` ignore `.idd/cache/` (*Ignore Rule* — every path). 3. Check for an existing `.idd.yml` (or legacy `.gitissue.yml`) and follow the merge path if found. 4. Scan the repository to detect language, framework, test runner, and size. 5. Suggest defaults based on detection. 6. Write `.idd.yml` to the repo root. 7. Print a report of detected values and next-step suggestions. ## Prerequisites Before any operation, verify the environment. On failure, output the exact error from `references/error-messages.md` and stop. 1. Confirm git repository: `git rev-parse --git-dir` That is the only prerequisite. This skill does not need `gh` or GitHub authentication — it generates a local config file. ### Bundled dependency precheck Verify that this skill's bundled template and reference files are present. If any are missing, stop immediately and print: ```text ✗ Missing bundled dependency: {missing_file} To fix: asm install https://github.com/luongnv89/idd --skill init-idd (or reinstall the full distribution) Plugin: claude plugin marketplace add luongnv89/idd claude plugin install idd@idd (or: claude plugin update idd@idd) Then restart the agent session and re-run /init-idd. ``` Check these files relative to the skill's directory (the dirname of this SKILL.md): - `templates/idd-template.yml` — canonical config template with all schema fields - `references/error-messages.md` — complete error catalog with triggers and exact output - `references/examples.md` — worked example runs - `references/run-stats.md` — run-stats footer contract (shape, fields, unavailable marker) - `references/review-contract.md` — report statuses, evidence, uncertainty, decision, format rule - `references/merge-strategy-check.md` — optional post-write merge-settings check - `references/docs/config-schema.md` — full configuration schema - `references/docs/naming-conventions.md` — naming conventions (referenced by generated config) - `references/docs/idd-methodology.md` — IDD methodology reference - `references/docs/github-projects-sync.md` — GitHub Projects status sync reference - `references/docs/platform-github.md` — GitHub platform driver reference - `references/docs/terminal-style.md` — terminal output style contract (symbols, output structure, table/error formats) - `references/docs/context-threshold.md` — context-threshold check contract - `references/scripts/gi-stack-detect.py` — language, framework, test-runner, and size detection ## Ignore Rule Runs once the prerequisites pass, before the *Configuration Check*, so **every** later outcome — create, overwrite, merge, cancel, auto-mode cancel, and each `BLOCKED` stop — has run it. It creates `.gitignore` when absent, mirrors each legacy `.gitissue[/<x>]` line as `.idd[/<x>]`, then adds `.idd/cache/`; a line already present is never added twice. "Present" is a literal match against this repo's own `.gitignore` (trimmed, one leading `/` ignored; `.idd/` also covers the cache) — **never** `git check-ignore`: a global or `.git/info/exclude` rule must not stand in for the committed one. Run it exactly, with `sh`, from `git rev-parse --show-toplevel`: <!-- a:init-gitignore --> ```sh # idd-gitignore f=.gitignore; if [ ! -f "$f" ]; then : > "$f" && echo "created $f"; fi has() { awk -v t="$1" 'function n(s) { gsub(/^[ \t]+|[ \t\r]+$/, "", s); sub(/^\//, "", s); return s } BEGIN { t = n(t); a = t; if (!sub(/\/$/, "", a)) a = a "/" } { l = n($0) } l == t || l == a || (l == ".idd/" && t !~ /^!/) { h = 1 } END { exit !h }' "$f"; } add() { has "$1" && return 0 [ -s "$f" ] && [ -n "$(tail -c 1 "$f")" ] && printf '\n' >> "$f" printf '%s\n' "$1" >> "$f" && echo "added $1"; } m=$(awk '{ gsub(/^[ \t]+|[ \t\r]+$/, "") } /^!?\/?\.gitissue(\/|$)/ { sub(/\.gitissue/, ".idd"); print }' "$f") printf '%s\n' "$m" | while IFS= read -r x; do [ -z "$x" ] || add "$x"; done add .idd/cache/ ``` Each `created` / `added` line is a change; none means `○ already ignored`. Any error output means the write failed: print *Could not update .gitignore* (`references/error-messages.md`) and continue — the config result stands. It feeds the `.gitignore:` report row. ## Configuration Check This skill GENERATES the config — it does not read one. Check if `.idd.yml` already exists in the repo root before proceeding. **Capture the run clock in that same check:** chain the first shell as `…; ec=$?; date +%s >&2; exit "$ec"` and keep the stderr epoch as `run_started_epoch` — the check's exit stays intact, it costs no extra round trip, and it is what the *Run Stats Footer* (`references/run-stats.md`) measures `elapsed` from. **Context threshold.** <!-- a:ctx-check --> Only when `compaction.enabled` is true (`references/docs/context-threshold.md`). This skill loads no config, so read `compaction.enabled` (default `true`) and `compaction.threshold.init-idd` (default `40`) from an existing `.idd.yml` when there is one, else use those defaults. Once, right after this check, compare the remaining-context figure the host placed in your context (none: skip silently, never estimate) with that threshold. At or below it, print the `⚠` line and a `/compact <focus>` line (skill and step only), then continue — no pause; auto mode prints only the `⚠` line. ### File does NOT exist — always create When the file is missing (and no legacy `.gitissue.yml` stands in for it — *Legacy names*), **always create it** without prompting. This happens regardless of context — even when the skill is invoked non-interactively from another skill. No early exit, no conditions, no cancel option. ``` ○ No .idd.yml found — generating config... ``` Proceed directly to **Step 1 — Scan Repository**. ### Legacy names A legacy `.gitissue.yml` with no `.idd.yml` beside it **is** the existing config — **never** create a fresh file over it. <!-- a:init-legacy-config --> Take *File exists* below with it as that file (the prompt names `.gitissue.yml`): merge reads it (every key kept, `security:` included) and writes `.idd.yml`; overwrite writes `.idd.yml`; after either, tell the user to `git rm .gitissue.yml`. Auto mode takes cancel: the legacy file stays untouched, no `.idd.yml` is written, and it prints `⚠ legacy .gitissue.yml found — rename to .idd.yml (git mv .gitissue.yml .idd.yml)`. When both exist, `.idd.yml` is the existing config. A legacy `.gitissue/` directory prints `○ legacy .gitissue/ found — move or delete its machine-local files:` and, on its own line, https://github.com/luongnv89/idd/blob/main/docs/migrating-from-gitissue.md ### File exists — ask user If the file already exists, show the prompt from `references/error-messages.md`: ``` ⚠ .idd.yml already exists Options: overwrite — replace with new auto-detected config merge — keep existing values, add new fields cancel — do nothing Choose: [overwrite/merge/cancel] ``` - **overwrite** — run full generation. Keep the existing file until Step 3 replaces it in one write. - **merge** — read the existing file. If it does not parse as YAML, print *Existing config does not parse* (`references/error-messages.md`), leave it untouched, and stop with `Result: BLOCKED`. Otherwise preserve every user-set value and add only the schema fields it lacks. - **cancel** — make no change to the config (the *Ignore Rule* already ran). Report `Result: CANCELLED`. - **Auto mode** (`--auto` or `IDD_AUTO_MODE=1`) — do not prompt. Print `⚠ Auto mode: overwrite/merge/cancel prompt skipped — kept the existing .idd.yml (cancel).` and take **cancel**, the safe default (the *Ignore Rule* still ran). --- ## Step 1 — Scan Repository Detect project characteristics by checking for specific files and directories. That is file-existence and dependency-name lookup, not reasoning, so run `references/scripts/gi-stack-detect.py` from the repo root (resolve the script path relative to this SKILL.md exactly as the *Bundled dependency precheck* resolves its list): ```bash python3 references/scripts/gi-stack-detect.py --root . ``` Exit 0 prints one JSON object: `language`, `framework`, `test_runner` (each with its `_source` file), `repo_size`, `file_count`, `file_count_source`, `issue_templates`, a `derived` block carrying the Step 2 values (`auto_test`, `test_timeout`, `stale_threshold_days`), and `unresolved`. **`unresolved` is the LLM fallback trigger, and the only one.** It names the fields nothing in the table matched. A `null` there is a real answer ("no marker file is present"), not a failure — the script never guesses. For each field it names, and *only* those, work it out yourself from the tables below; leave every resolved field exactly as the script reported it. `file_count_source` says whether the count came from `git ls-files` or a filesystem walk; report the count as given rather than re-deriving it. Classify **every** outcome: | Outcome | Meaning | Do | |---------|---------|----| | exit 0 | detected | use the output; resolve `unresolved` fields from the tables below | | exit 3 | invalid input — a bad `--root` or `--rules` file | **stop**; print the error from `references/error-messages.md` (*Stack detection failed*). Never degrade past exit 3 | | script file absent | broken install, not a runtime problem | stop with the `✗ Missing bundled dependency` block above | | no `python3`, exit 2, exit 4, unparsable stdout | environment problem | print `⚠ gi-stack-detect unavailable — detecting inline` and run the whole of the tables below by hand | Pass `--rules FILE` to replace a built-in table for a repository the defaults do not describe — a JSON object of `{"language": [[glob, name]], "framework": [[dependency, name]], "test_runner": [[kind, pattern, name]]}`, where each key replaces the matching table outright. ### Language Detection Check for these files in the repo root (or nearby): | File | Language | |------|----------| | `package.json` | JavaScript / TypeScript (check for `"typescript"` in devDependencies to distinguish) | | `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` | Python | | `go.mod` | Go | | `Cargo.toml` | Rust | | `pom.xml`, `build.gradle`, `build.gradle.kts` | Java | | `Gemfile` | Ruby | | `*.csproj`, `*.sln` | C# | If several language markers exist, use the one at the repo root. If several are at the root, use the language with the most source files. If none is detected, use empty state. ### Framework Detection Parse dependency files to identify frameworks: | Dependency name | Framework | |-----------------|-----------| | `react`, `react-dom` | React | | `next` | Next.js | | `vue` | Vue.js | | `nuxt` | Nuxt.js | | `angular`, `@angular/core` | Angular | | `express` | Express | | `fastify` | Fastify | | `django` | Django | | `flask` | Flask | | `fastapi` | FastAPI | | `rails`, `railties` | Rails | | `spring-boot`, `spring-core` | Spring | | `gin-gonic/gin` | Gin | | `actix-web` | Actix | | `ASP.NET`, `Microsoft.AspNetCore` | ASP.NET | Check `package.json` dependencies/devDependencies, `requirements.txt` lines, `pyproject.toml` dependencies, `Gemfile` gems, `go.mod` require blocks, `Cargo.toml` dependencies, `pom.xml`/`build.gradle` dependencies. If no framework is detected, print the `○ skip` Framework row (not an error). ### Test Runner Detection Look for these files and patterns: | Marker | Test runner | |--------|-------------| | `jest.config.js`, `jest.config.ts`, `jest.config.mjs`, `"jest"` in `package.json` | Jest | | `vitest.config.js`, `vitest.config.ts`, `"vitest"` in `package.json` | Vitest | | `.mocharc.yml`, `.mocharc.js`, `"mocha"` in `package.json` | Mocha | | `karma.conf.js` | Karma |