Skip to content

A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.

chore(idd): migrate .gitissue.yml to .idd.yml (#212)

Luong NGUYENcd3d4ebaf6eb
diff --git a/.gitignore b/.gitignore
index fcaaee6..099dbf3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -100,3 +100,4 @@ scripts/.vendor-cache/
# Local agent/tooling state
.asm-improver/
.gitissue/
+.idd/
diff --git a/.gitissue.yml b/.gitissue.yml
deleted file mode 100644
index c3ede4d..0000000
--- a/.gitissue.yml
+++ /dev/null
@@ -1,14 +0,0 @@
-# gitissue / IDD configuration for claude-howto
-#
-# This is a documentation/tutorial repo. Doc-sync PRs (e.g. "docs: sync to
-# Claude Code vX") are not tied to a single tracked issue, so they are treated
-# like chore/refactor PRs for traceability: they do not require a `Closes #N`.
-# A PR opts in by including a `Type: docs` (or `Type: chore`/`Type: refactor`)
-# line in its body.
-
-review:
- # Add `docs` to the built-in refactor/chore exemption so documentation-sync
- # PRs are not hard-blocked on a missing `Closes #N`. The other three
- # traceability checks still run.
- traceability_exempt_pattern: "^\\s*Type:\\s*(refactor|chore|docs)\\s*$"
- traceability_exempt_labels: ["refactor", "chore", "documentation"]
diff --git a/.idd.yml b/.idd.yml
new file mode 100644
index 0000000..83ac25e
--- /dev/null
+++ b/.idd.yml
@@ -0,0 +1,312 @@
+# IDD Stack configuration
+# Generated by /init-idd (merged from legacy .gitissue.yml)
+# Detected: Python | no framework | pytest | medium repo (675 files)
+# Python is the scripts/ toolchain only (EPUB build + doc validators, tests in
+# scripts/tests); the tutorial itself is Markdown in the 01- to 10- modules.
+#
+# gitissue / IDD configuration for claude-howto
+#
+# This is a documentation/tutorial repo. Doc-sync PRs (e.g. "docs: sync to
+# Claude Code vX") are not tied to a single tracked issue, so they are treated
+# like chore/refactor PRs for traceability: they do not require a `Closes #N`.
+# A PR opts in by including a `Type: docs` (or `Type: chore`/`Type: refactor`)
+# line in its body.
+
+# Platform for issue management
+# Values: "github" (only implemented driver — see references/docs/platform-github.md)
+platform: github
+
+# Issue creation and normalization settings
+issue:
+ # Auto-normalize issues in /issue-resolver before resolution
+ auto_normalize: true
+
+ # Issue template source
+ # Values: "default" | path to custom template directory
+ # Note: .github/ISSUE_TEMPLATE/ found (5 templates)
+ # Set template to ".github/ISSUE_TEMPLATE" to use your existing templates
+ template: default
+
+ # Auto-suggest labels based on issue content and type
+ labels_auto_suggest: true
+
+ # Post a comment when normalizing an issue
+ normalize_comment: true
+
+# Deterministic duplicate scoring. Payments come only from newly consumed,
+# canonical item tokens; extra stop words extend (never replace) built-ins.
+duplicate_detection:
+ weights:
+ # Keep phrase >= title_overlap so extra stop words cannot raise scores.
+ phrase: 2
+ title_overlap: 2
+ keyword: 1
+ same_type: 1
+ high_threshold: 5
+ medium_threshold: 3
+ min_token_length: 1
+ phrase_min_tokens: 3
+ backlog_limit: 100
+ max_items: 100
+ extra_stop_words: ""
+
+# Resolution pipeline settings
+resolve:
+ # Approval gate for the plan phase
+ # Values: "auto" | "comment-and-wait"
+ approval_gate: auto
+
+ # Branch naming prefix
+ # "auto" uses type-based prefixes: fix/, feat/, refactor/, docs/, test/, chore/
+ # Branch format: {type}/{issue_number}-{short-description}
+ # Examples: fix/42-mobile-auth-redirect, feat/15-add-dark-mode
+ # Set a custom string (e.g., "issue-") to override type-based naming
+ # See references/docs/naming-conventions.md for the full branch/commit/PR grammar
+ branch_prefix: "auto"
+
+ # Run tests before creating PR
+ auto_test: true
+
+ # Abort verify phase after N seconds
+ # Range: 30-3600
+ test_timeout: 300
+
+ # Warn if resolve produces more than N commits
+ max_commits: 10
+
+ # Max QA review-fix cycles during resolve Step 4
+ qa_max_cycles: 5
+
+ # Scale the resolve pipeline to issue complexity (adaptive effort).
+ # true: trivial issues (Effort XS/S) take a lighter, faster path; complex or
+ # ambiguous issues keep the full pipeline. false: full pipeline for every issue.
+ adaptive_effort: true
+
+ # Borrow catalogued-but-not-installed skills for one resolve task.
+ # false: propose only already-installed skills. true: offer the catalog,
+ # install selected missing skills, record in run-state, teardown borrowed only.
+ borrow_skills: false
+
+ ui_review:
+ browser_review: ask
+
+# Triage settings
+triage:
+ # Flag issues with no activity beyond this threshold (days)
+ stale_threshold_days: 14
+
+ # Suggest priorities based on type, age, and dependency position
+ auto_priority: true
+
+ # Include recently closed issues in triage analysis
+ include_closed: false
+
+ # Max seconds to scan codebase per issue for file dependencies
+ scan_timeout_per_issue: 30
+
+# PR review settings (used by /issue-pr-review and /auto-pilot)
+review:
+ max_cycles: 3
+ # Scale review depth to PR complexity (adaptive depth).
+ # true: a trivial PR caps the review-fix loop at 1 cycle and skips optional
+ # passes; complex or ambiguous PRs keep full depth. false: full depth always.
+ adaptive_depth: true
+ auto_merge: false
+ confidence_threshold: 80
+ run_tests: true
+ check_ci: true
+ # Opt-in: report a terminal CI failure without blocking the review gate.
+ # GitHub exposes no API field naming a billing-related failure, so this
+ # ignores ANY terminal CI failure, not only billing ones. CI is still polled
+ # and still reported. Review gate only: no merge gate is relaxed
+ # (/issue-pr-review --auto, /auto-pilot), so merge that PR by hand.
+ ignore_ci_billing_failures: false
+ ci_poll_interval: 30
+ ci_timeout: 600
+ test_timeout: 300
+ soft_pass: true
+ require_acceptance_criteria_check: true
+ require_traceability_check: true
+ # Add `docs` to the built-in refactor/chore exemption so documentation-sync
+ # PRs are not hard-blocked on a missing `Closes #N`. The other three
+ # traceability checks still run.
+ traceability_exempt_pattern: "^\\s*Type:\\s*(refactor|chore|docs)\\s*$"
+ traceability_exempt_labels: ["refactor", "chore", "documentation"]
+ ui_review:
+ browser_review: ask
+
+# Auto-pilot settings (used by /auto-pilot)
+autopilot:
+ # Merge mode — controls when /auto-pilot is allowed to merge PRs.
+ # Values: "conservative" | "balanced" | "aggressive"
+ # Default: "balanced" — auto-merge clean PRs (review passed). PRs with unresolved
+ # review issues get a follow-up and stay open. Recommended for most projects.
+ # "conservative": create PR, run review-fix cycles, leave PR open.
+ # Never auto-merges.
+ # "aggressive": auto-merge clean PRs AND merge partial PRs when
+ # merge_partial=true is also set (see below). Risky —
+ # only enable on disposable/experimental repos.
+ mode: balanced
+
+ # Allow merging PRs that still have unresolved fixable review issues.
+ # Default: false — never merge a partial PR.
+ # Only honored when mode is "aggressive". With any other mode this
+ # field is ignored. Combined opt-in (mode=aggressive AND merge_partial=true)
+ # is required to reach the prior 2.1.x "merge anyway with follow-up" path.
+ merge_partial: false
+ max_iterations: 10
+ # Resolver-only concurrency for one independent triage group (1..8). Review,
+ # merge, run-log, state/cache writes, and cleanup always remain serialized.
+ # The default 1 preserves the original in-place sequential path exactly.
+ max_parallel: 1
+ review_cycles: 3
+ auto_merge: true
+ pause_on_failure: false
+ skip_labels:
+ - wontfix
+ - blocked
+ - do-not-merge
+ critical_labels:
+ - critical
+ - priority:critical
+ respect_dependencies: true
+ # Reuse .idd/triage.json when younger than this many minutes and no
+ # commit landed since (0 disables reuse); force a full re-triage every Nth
+ # iteration (0 = never — a pick miss forces one regardless).
+ triage_cache_max_age_minutes: 60
+ retriage_every: 0
+ # Quarantine an issue after this many consecutive failed runs by applying
+ # quarantine_label; every later run then skips it until a human removes the
+ # label (0 disables quarantine). The label is the durable state — the count
+ # is derived from .idd/runs.jsonl and fails open.
+ quarantine_after: 3
+ quarantine_label: "auto-pilot-quarantined"
+ # Wall-clock budget for one /auto-pilot run in minutes, measured from the run
+ # state's started_at: at the budget the loop stops cleanly with its report
+ # written and its lock released (0 = unbounded).
+ max_runtime_minutes: 0
+
+# Issue analysis settings
+analysis:
+ # Max files to read during deep analysis (5-100)
+ max_files: 30
+
+ # How many levels of import dependencies to trace (1-5)
+ trace_depth: 3
+
+ # Max seconds for the full codebase scan phase (30-600)
+ scan_timeout: 120
+
+# GitHub Projects board sync settings
+# See references/docs/github-projects-sync.md for the full integration reference
+projects:
+ # Enable automatic project board status sync
+ # When false, all project sync operations are silently skipped
+ sync_enabled: false
+
+ # Explicit project number (null auto-detects the first linked project)
+ project_number: null
+
+ # Name of the Status field on the project board
+ status_field: "Status"
+
+ # Map of internal status keys to project board option values
+ status_map:
+ # Status for newly created issues
+ todo: "Todo"
+ # Status when work starts (branch created)
+ in_progress: "In Progress"
+ # Status when PR is created
+ done: "Done"
+
+# Model suggestion settings (used by /issue-creator)
+model_suggestion:
+ # Suggest a cost-effective model + thinking level per issue, from CursorBench
+ # data cached per user in ~/.cache/idd/model-data-<date>.json (shared
+ # across all repos, not per-project). When false, silently skipped.
+ enabled: true
+
+ # Source URL refreshed into the cache on opt-in or via --refresh-model-data
+ data_url: "https://cursor.com/cursorbench"
+
+ # Days before cached model data is considered stale
+ cache_ttl_days: 7
+
+# Pre-commit security scan settings (every skill that commits or pushes)
+# The built-in rules always apply; these keys only extend them. There is no key
+# that disables a rule — a scan a repository can switch off is not a gate.
+security:
+ # Extra regex ORed onto the built-in secret-bearing filename pattern
+ # Example: "(^|/)service-account\\.json$"
+ extra_secret_file_pattern: ""
+
+ # Extra regex ORed onto the built-in real-API-key value pattern
+ # Prefer prefix + length over identifier + value
+ # Example: "acme_live_[A-Za-z0-9]{24,}"
+ extra_secret_value_pattern: ""
+
+ # Paths matching this regex are skipped entirely (fixtures, golden files)
+ # Every path it excludes is a path no rule can block — keep it narrow
+ # Example: "^tests/fixtures/"
+ allow_pattern: ""
+
+ # Warn (never block) when a scanned file exceeds this size, in megabytes
+ max_file_size_mb: 10
+
+# Context-threshold compaction (long-running runs)
+# When the host shows the agent how much context is left and it is at or below
+# a skill's threshold, the skill confirms its progress is checkpointed and
+# prompts /compact (it never compacts by itself). After a compaction it resumes
+# from durable state. Contract:
+# https://github.com/luongnv89/idd/blob/main/docs/context-threshold.md
+compaction:
+ # false = every skill behaves exactly as without this section
+ enabled: true
+
+ # Percent of context remaining, integer 1-99, one key per skill
+ threshold:
+ auto-pilot: 15
+ issue-resolver: 40
+ issue-pr-review: 40
+ issue-analysis: 40
+ issue-creator: 40
+ issue-triage: 40
+ plan-to-issues: 40
+ init-idd: 40
+
+# Per-role subagent model / thinking-effort overrides (optional)
+# null = pass nothing; the subagent inherits the main agent's configuration.
+# Values are opaque strings your harness accepts (letters, digits and
+# . _ : / [ ] - only, max 64 chars). A role left null takes its `default`.
+# Quote a value containing [ or ], e.g. default: "sonnet[1m]" — unquoted it
+# only parses with PyYAML; without it the whole config degrades to defaults.
+agents:
+ # Model name per subagent role
+ model:
+ default: null
+ codebase-researcher: null
+ synthesizer: null
+ implementer: null
+ code-reviewer: null
+ ui-reviewer: null
+ fixer: null
+ duplicate-detector: null
+ issue-relationship-scanner: null
+ autopilot-resolver: null
+ autopilot-reviewer: null
+ autopilot-analyzer: null
+
+ # Thinking effort per subagent role
+ effort:
+ default: null
+ codebase-researcher: null
+ synthesizer: null
+ implementer: null
+ code-reviewer: null
+ ui-reviewer: null
+ fixer: null
+ duplicate-detector: null
+ issue-relationship-scanner: null
+ autopilot-resolver: null
+ autopilot-reviewer: null
+ autopilot-analyzer: null