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/.gitignoreindex 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.ymldeleted file mode 100644index 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.ymlnew file mode 100644index 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