takt-skill-updater

TAKT Skill Updater

Bring the takt-* skill group up to date with the latest version in accordance with new release tags of nrslib/takt.

Prerequisite takt version: v0.47.0

About path notation

This skill uses paths beginning with skills/ . Read the actual paths according to the execution environment:

Environment	Prefix
Claude Code	.claude/skills/
Codex CLI	.codex/skills/
Common (actual)	.agents/skills/

The source of truth for takt is the nrslib/takt checkout pointed to by the environment variable TAKT_SRC . It does not depend on git submodules or the layout of a specific repository; use the procedure in Step 0 to directly clone and use nrslib/takt.

Target skills

Skill	Actual path	Check target
takt-task-builder	skills/takt-task-builder/SKILL.md	TaskRecord schema, status transitions, field list
takt-workflow-builder	skills/takt-workflow-builder/SKILL.md	Built-in workflow list, YAML structure, new feature fields
takt-facet-builder	skills/takt-facet-builder/SKILL.md	Facet types, style guide reference paths
takt-analyzer	skills/takt-analyzer/SKILL.md	Engine specification reference, built-in paths
takt-optimizer	skills/takt-optimizer/SKILL.md	Log format, optimization parameters

Workflow

Step 0: Obtain the takt source

Prepare a checkout of nrslib/takt and set it toTAKT_SRC . If you have an existing checkout on hand, you may specify it as TAKT_SRC . If an update target version is specified (such as when called from CI), set that tag to NEW_VERSION . If TAKT_SRC with the target tag already checked out is given, this Step may be omitted.

TAKT_SRC="${TAKT_SRC:-/tmp/takt}"
if [[ ! -d "$TAKT_SRC" ]]; then
  git clone https://github.com/nrslib/takt.git "$TAKT_SRC"
fi
git -C "$TAKT_SRC" fetch --tags
# NEW_VERSION 指定時はそのタグを、未指定時は最新の安定版タグを checkout する
git -C "$TAKT_SRC" checkout \
  "${NEW_VERSION:-$(git -C "$TAKT_SRC" tag --list 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)}"

Step 1: Check the takt version

takt checkout (TAKT_SRC) with the version that each skill assumes.

# 更新先の takt バージョン（TAKT_SRC のチェックアウトから取得）
NEW_VERSION=$(git -C "$TAKT_SRC" describe --tags --abbrev=0)
echo "更新先のtaktバージョン: ${NEW_VERSION}"

# 各スキルの前提バージョン（旧バージョンの特定に使う）
grep -r "前提 takt バージョン" skills/takt-*-builder/SKILL.md skills/takt-analyzer/SKILL.md skills/takt-optimizer/SKILL.md

From the prerequisite version of each skill, identify the old version (OLD_VERSION). If all skills have the same version, use that value. If they differ, use the oldest version as OLD_VERSION .

OLD_VERSION と NEW_VERSION match, no update is needed. If there is a difference, proceed to Step 1.5.

Step 1.5: Synchronize reference files

TAKT_SRC From the checkout of references/takt/ directory of each skill, synchronize the reference files. rsync --delete ensures that files deleted on the takt side are also automatically deleted from the skill side.

# sync スクリプトがある場合（TAKT_SRC で更新元を指定する）
TAKT_SRC="$TAKT_SRC" scripts/sync-takt-references.sh --dry-run
TAKT_SRC="$TAKT_SRC" scripts/sync-takt-references.sh

In repos where the sync script does not exist, individually synchronize the subset referenced by each skill with rsync -a --delete .builtins/, docs/, builtins/skill/references/, src/infra/task/, src/core/logging/, src/core/workflow/ etc., only the range that the skill actually reads should be synchronized.

Each skill is synchronized with only the subset of takt resources that it references. For the definition of synchronization targets, refer to each skill section in scripts/sync-takt-references.sh .

Quality check of synchronized content (prevention of misreading)

Do not blindly copy just because "the upstream project wrote it that way." Read the documents added or changed in the sync, and check whether there are any descriptions that could lead to misreading (such as errors in configuration examples, explanations that contradict the official reference, or configuration key notation with ambiguous nesting structure), by cross-checking against the authoritative information sources (docs/configuration.md, schema definitions, implementation code).

Actions when detected:

1. Fix the snapshot side and append to the "Record of Local Fixes" (at the end of this file)
2. Always check the existing record entries after every sync. If fixed upstream, delete them from the record; if not fixed, reapply the same fix (rsync --delete because they are overwritten and lost by)
3. Consider reporting to upstream (nrslib/takt) via issue / PR (reporting leads to making the fix permanent)

Step 2: Obtain the diff between tags

Obtain the diff between the old version and the current version, and determine which skills are affected.

cd "$TAKT_SRC"

# 変更されたファイル一覧
git diff --name-only ${OLD_VERSION}..${NEW_VERSION}

# 変更の統計（追加/削除行数）
git diff --stat ${OLD_VERSION}..${NEW_VERSION}

# 変更履歴（コミットメッセージ）
git log --oneline ${OLD_VERSION}..${NEW_VERSION}

Determining affected skills

Determine affected skills from the changed file paths. Skip the subsequent steps for skills that are not affected.

Changed file path pattern	Affected skill
src/infra/task/taskRecordSchemas.ts, src/infra/task/taskExecutionSchemas.ts	takt-task-builder
builtins/**/workflows/*.yaml	takt-workflow-builder
builtins/**/facets/**	takt-facet-builder
builtins/**/*STYLE_GUIDE*.md	takt-facet-builder
builtins/skill/references/engine.md	takt-analyzer, takt-workflow-builder
builtins/skill/references/yaml-schema.md	takt-workflow-builder
src/**/log*, src/**/trace*	takt-optimizer

Step 3: Detailed check of affected skills

For skills determined to be affected, check the details of the diff between tags and identify what needs to be reflected in each skill.

cd "$TAKT_SRC"

# 影響ファイルの詳細差分を確認（例）
git diff ${OLD_VERSION}..${NEW_VERSION} -- src/infra/task/taskRecordSchemas.ts src/infra/task/taskExecutionSchemas.ts
git diff ${OLD_VERSION}..${NEW_VERSION} -- builtins/ja/workflows/
git diff ${OLD_VERSION}..${NEW_VERSION} -- builtins/ja/facets/
git diff ${OLD_VERSION}..${NEW_VERSION} -- builtins/skill/references/

Check only the following areas that have been determined to be affected.

a) TaskRecord schema diff (→ takt-task-builder)

In the diff, src/infra/task/taskRecordSchemas.ts と src/infra/task/taskExecutionSchemas.ts check the changes to and identify what needs to be reflected from the following perspectives:

Check item	Reference source	Update destination
Status enum values	TaskStatusSchema	skills/takt-task-builder/references/task-schema.md
TaskExecutionConfig fields	TaskExecutionConfigSchema	skills/takt-task-builder/references/task-schema.md
TaskRecord fields	TaskRecordSchema	skills/takt-task-builder/references/task-schema.md
superRefine validation	TaskRecordSchema.superRefine	skills/takt-task-builder/references/task-schema.md status transition table
TaskFailure structure	TaskFailureSchema	skills/takt-task-builder/references/task-schema.md

b) Built-in workflow diff (→ takt-workflow-builder)

In the diff, builtins/**/workflows/*.yaml(old builtins/**/pieces/*.yaml) check the changes to and identify what needs to be reflected from the following perspectives:

Check item	Update destination
Workflow name rename	skills/takt-workflow-builder/SKILL.md built-in table
Newly added workflow	skills/takt-workflow-builder/SKILL.md built-in table
Deleted workflow	skills/takt-workflow-builder/SKILL.md built-in table
New workflow YAML field	skills/takt-workflow-builder/SKILL.md design decision guide

c) Facet structure diff (→ takt-facet-builder)

In the diff, builtins/**/facets/** と *STYLE_GUIDE*.md check the changes to and identify what needs to be reflected from the following perspectives:

Check item	Update destination
Changes to style guide content	skills/takt-facet-builder/SKILL.md reference material table
Addition/change of facet types	skills/takt-facet-builder/SKILL.md facet creation conventions
New built-in facet	skills/takt-facet-builder/SKILL.md reference example

d) Engine specification diff (→ takt-analyzer, takt-optimizer)

Check the changes under builtins/skill/references/ in the diff, and identify what needs to be reflected from the following perspectives:

Check item	Update destination
Change in rule evaluation method	skills/takt-analyzer/SKILL.md, skills/takt-workflow-builder/SKILL.md
New step type	skills/takt-workflow-builder/SKILL.md
Log format change	skills/takt-optimizer/SKILL.md
Addition of template variables	skills/takt-task-builder/references/task-schema.md

Step 4: Perform skill updates

Based on the changes identified in Step 3, update the affected skills.

Update rules

1. Version notation: Update to > **前提 takt バージョン**: を NEW_VERSION in each SKILL.md
2. Field addition: Add new fields at the end of the existing table (preserve order)
3. Rename: Add a note about old name → new name (e.g., "In v0.28.1, expert → dual rename")
4. Deletion: Remove from the table and mention it in a note
5. Reference documents: skills/takt-task-builder/references/task-schema.md Also update reference files such as

List of files to update

File	Update content
skills/takt-task-builder/SKILL.md	Status transition table, field references, workflow name examples
skills/takt-task-builder/references/task-schema.md	Field list, status transition diagram, invariant table
skills/takt-workflow-builder/SKILL.md	Built-in workflow table, YAML structure examples, design decision guide
skills/takt-facet-builder/SKILL.md	Reference paths, facet creation conventions
skills/takt-analyzer/SKILL.md	Reference paths, analysis criteria
skills/takt-optimizer/SKILL.md	Log format, optimization parameters

Updating takt-skill-updater itself

Once the updates to the target skills are complete, update this skill itself as well:

1. Update to > **前提 takt バージョン**: を NEW_VERSION at the beginning
2. Append this change to the "Past update history" section at the end

Step 5: Validation

Check consistency after the update.

Automatic verification

# order.md バリデーション（takt-task-builder）
bash skills/takt-task-builder/scripts/validate-order-md.sh

# ワークフロー・ファセット バリデーション（takt-workflow-builder）
bash skills/takt-workflow-builder/scripts/validate-takt-files.sh --workflows

Manual verification checklist

• Updated to 前提 takt バージョン が NEW_VERSION in all SKILL.md files
• task-schema.md status enum of skills/takt-task-builder/references/takt/src/infra/task/taskRecordSchemas.ts の TaskStatusSchema matches
• task-schema.md The field list in TaskRecordSchema と TaskExecutionConfigSchema covers all fields in
• task-schema.md The invariant table in superRefine matches the validation rules in
• takt-workflow-builder/SKILL.md built-in table of skills/takt-workflow-builder/references/takt/builtins/ja/workflows/ is consistent with the actual state
• takt-workflow-builder/SKILL.md remain
• takt-facet-builder/SKILL.md exist
• takt-analyzer/SKILL.md exist
• takt-skill-updater's own 前提 takt バージョン and "Past update history" have been updated
• All entries in "Record of local modifications" have been reapplied to the post-sync snapshot (or the upstream fix has been confirmed and they have been removed from the record)

Step 6: Commit and PR

Commit the updates.

Branch naming convention

chore/update-takt-skills-for-v{バージョン}

Example: chore/update-takt-skills-for-v031

Commit message template

chore: update takt-* skills for takt v{バージョン}

- Add "前提 takt バージョン: v{バージョン}" to all takt-* skills
- takt-task-builder: {変更サマリ}
- takt-workflow-builder: {変更サマリ}
- Sync takt reference snapshots to v{バージョン}

Record of local modifications

Local modifications to the snapshot for descriptions that invite misreading of the upstream documentation. Sync (rsync --deleteis lost each time, so it is reapplied every time during the Step 1.5 quality check. Once the fix is released upstream, delete the corresponding line.

Target file	Fix details	Date added	Removal condition
docs/testing/e2e.md(under each skill at the sync destination references/takt/ )	In the Observability E2E procedure configuration example, usage_events_phase / monitor / session_log_exporter に observability. prefix is added (because it would be misread as a top-level setting. The correct one is docs/configuration.md の observability subfield)	2026-06-11	Delete once the same location upstream is fixed

Past update history

Record major changes here so they can be referenced during future updates.

v0.46.0 → v0.47.0（2026-06-18）

Skill	Change details
All skills	前提 takt バージョン: v0.47.0 updated to.v0.47.0 tag reference snapshot synced
takt-task-builder	No changes to TaskRecord / TaskExecutionConfig schema. Only version notation updated
takt-workflow-builder	BREAKING: provider_options.$ref → extends(bare name) migration reflected in 3 places: YAML examples, design decision guide, and v0.47.0 changes.persona_providers deprecated →provider_routing（personas/tags/steps 3 axes) noted in changes. Added takt-default-with-fc・peer-review-with-fc to the built-in table. Finding Contract (finding_contract: section) YAML examples and design decision guide added. Step tags (tags: field) Parallel Step examples and design decision guide added.provider-options/ directory move (builtins/{lang}/workflows/provider-options/ → builtins/{lang}/provider-options/) noted in changes. Trace discovery enhancement (WorkflowTraceTaskMetadata) noted in changes
takt-facet-builder	Persona に findings-manager added. Added findings-manager to Instruction. Added findings-manager・*-finding-contract family (11 items) to Output Contract. Added note on v0.47.0 changes
takt-analyzer	Added traceDiscovery.ts to the reference materials table. Added provider_options.$ref deprecation check and provider_routing migration check to the workflow structure analysis checklist
takt-optimizer	Added optimization items for provider_options.$ref → extends migration and persona_providers → provider_routing migration to the loop control improvement section

v0.45.0 → v0.46.0（2026-06-17）

Skill	Change details
All skills	前提 takt バージョン: v0.46.0 updated to.v0.46.0 tag reference snapshot synced
takt-task-builder	No changes to TaskRecord / TaskExecutionConfig schema. Only version notation updated
takt-workflow-builder	requirements-reviewer removed,pure-reviewer added (review-pure instruction + pure-review output contract) reflected in the built-in table.provider_options.$ref common YAML reference and built-in presets (provider-options/{edit,review-files,review-readonly,review-web}.yaml) added to the design decision guide.provider_options.opencode.allowed_tools・provider_options.kiro.agent added to the design decision guide table.team_leader.max_parts → max_concurrency + max_total_parts split noted in the v0.46.0 addition examples
takt-facet-builder	From Persona requirements-reviewer removed and pure-reviewer added. Removed review-requirements from Instruction and added review-pure . Removed requirements-review from Output Contract and added pure-review . Added note on v0.46.0 changes
takt-analyzer	OTLP export (OTEL_EXPORTER_OTLP_ENDPOINT span / metric transmission when configured), nesting of provider spans via W3C trace context propagation,workflow_start.<name> span support for discovering running workflows added to the observability section
takt-optimizer	Added OTLP span / metric to the log source table in the "Optimization based on log diagnosis results" section

v0.44.0 → v0.45.0（2026-06-11）

Skill	Changes
All skills	前提 takt バージョン: v0.45.0 updated to.v0.45.0 Synced reference snapshot of tag
takt-task-builder	No changes to TaskRecord / TaskExecutionConfig schema. Only version notation updated
takt-workflow-builder	No changes to builtins. Only version notation updated
takt-facet-builder	No changes to facets/style guides. Only version notation updated
takt-analyzer	observability.usage_events_phase: true is now functional (no-op in v0.44.0). Added new log file .takt/runs/<run>/logs/<session>-usage-events.phase.jsonl（PhaseUsageEventLogRecord type NDJSON) to log locations and formats.phaseUsageEvent.ts added to reference materials table.UsageEventLogRecord.usage に cache_creation_input_tokens / cache_read_input_tokens added
takt-optimizer	Added new log source -usage-events.phase.jsonl(phase-granularity token aggregation) to the log source table in the "Optimization based on log diagnosis results" section

v0.43.0 → v0.44.0（2026-06-10）

Skill	Changes
All skills	前提 takt バージョン: v0.44.0 updated to.v0.44.0 Synced reference snapshot of tag (sync with the tag's worktree specified as TAKT_SRC )
takt-task-builder	No changes to TaskRecord / TaskExecutionConfig schema. Only version notation and reference docs synced
takt-workflow-builder	coding-review Expanded parallel review to all built-in review / review-fix / development workflows (backend, frontend, dual, terraform and their variants) (*-mini と compound-eye excluded). Configured with new provider kiro（kiro-cli、kiro_api_key / kiro_cli_path reflected
takt-facet-builder	No changes to facets/style guides. Only version notation updated
takt-analyzer	Added observability opt-in output (.takt/runs/<run>/monitor.json metrics, OTel span-derived shadow session log) to log locations and formats.span-to-ndjson-mapper.ts Add to reference materials. To the NDJSON record table, phase_judge_stage append
takt-optimizer	No change to the log format itself. Only the version notation is updated

v0.42.0 → v0.43.0（2026-06-02）

Skill	Changes
All skills	前提 takt バージョン: v0.43.0 updated to.v0.43.0 Synchronize the reference snapshot of the tag
sync-takt-references.sh	TAKT_SRC Allow the update source checkout to be specified via an environment variable, and root references/takt enabled synchronization even for checkouts without
takt-task-builder	There are no new changes to the TaskRecord schema itself. The existing managed_pr / resume_point description is maintained, and reference docs are synchronized to v0.43.0
takt-workflow-builder	frontend-maintenance workflow, to peer review coding-review addition,quality_gates.type: command reflected
takt-facet-builder	coding-reviewer、existing-system-respect, maintenance-related instructions,existing-system knowledge、coding-review / maintenance-scope output contract added to built-in examples
takt-analyzer	Added static analysis perspective to command quality gate
takt-optimizer	Added cleanup perspective to command quality gate

v0.36.0 → v0.42.0（2026-05-21）

Skill	Changes
All skills	前提 takt バージョン: v0.42.0 updated to.references/takt の source of truth を references/okite-ai/references/takt Specify the repo layout to be read as
takt-task-builder	managed_pr constraints,source: pr_review と pr_number relationship,resume_point structure to references/task-schema.md reflected in
takt-workflow-builder	default-draft / default-high / default-mini / default-peer-review / draft / peer-review / auto-improvement-loop / takt-default-refresh-* Reflect the addition of built-ins for / CQRS review.provider_options.<provider>.effort Added judgment criteria for
takt-facet-builder	Corrected to note that templates are not abolished but are auxiliary references.ai-antipattern-* Updated to the built-in list as of v0.42.0, including / research / terraform / character persona, etc.
takt-analyzer	NDJSON record name updated to workflow_* and log type reference corrected to src/shared/utils/types.ts .step_start.providerOptions* Added to diagnostic perspectives
takt-optimizer	前提 takt バージョン: v0.42.0 updated to
takt-skill-updater	When the sync script is absent, rsync Added base synchronization procedure

v0.35.4 → v0.36.0（2026-04-16）

Skill	Changes
All skills	前提 takt バージョン: v0.36.0 updated to
takt-task-builder	BREAKING: piece, start_movement, exceeded_max_movements alias completely abolished.schema.ts を taskRecordSchemas.ts + taskExecutionSchemas.ts reflected split. New fields: resume_point(for sub-workflow resumption). Template variable {max_movements} → {max_steps}、{movement_iteration} → {step_iteration}。instruction_template completely abolished
takt-workflow-builder	BREAKING: movements/initial_movement/max_movements/piece_config/piece_categories alias completely abolished. New step types: call: sub-workflow call (subworkflow: { callable: true } required, maximum nesting depth 5),kind: system AI-less system step (system_inputs:, effects:). New fields: structured_output: { schema_ref: } + schemas: definition. New rule conditions: when: deterministic conditions (comparison operators,context.*/structured.*/effect.* reference).instruction_template completely abolished
takt-facet-builder	New built-in policy screen-api added (screen-only API policy, applied to all dual-type workflows)
takt-analyzer	Reference path update: src/core/piece/evaluation/RuleEvaluator.ts → src/core/workflow/evaluation/RuleEvaluator.ts。when: Added support for deterministic condition evaluation
sync-takt-references.sh	src/core/piece/evaluation → src/core/workflow/evaluation path updated.schema.ts Synchronize taskRecordSchemas.ts + taskExecutionSchemas.ts Extended to

v0.31.0 → v0.35.4（2026-04-13）

Skills	Changes
All skills	前提 takt バージョン: v0.35.4 Updated to. Large-scale terminology rename: piece → workflow、movement → step、pieces/ → workflows/、initial_movement → initial_step、max_movements → max_steps、piece_config → workflow_config. Old names remain compatible as aliases
takt-task-builder	piece → workflow(alias compatible),start_movement → start_step、exceeded_max_movements → exceeded_max_steps. New field: run_slug, should_publish_branch_to_origin, source（pr_review/issue/manual）, pr_number（source: pr_review required at
takt-workflow-builder	pieces/ → workflows/ directory move. Workflow YAML's movements → steps、initial_movement → initial_step、max_movements → max_steps. Built-in table refresh: review separated (review-default, review-backend etc.), audit workflows newly added (audit-architecture, audit-e2e, audit-security, audit-unit etc.).e2e-test/unit-test removed → merged into audit
takt-facet-builder	Template directory abolished (changed to existing facet references). Many new facets added: Instruction (architecture-audit-*, audit-security-*, e2e-audit-*, e2e-coverage-*, unit-audit-*, write-tests-first）、Knowledge（e2e-testing, react, unit-testing）、Output Contract（architecture-audit-*, audit-security, e2e-audit-*, e2e-coverage-plan, plan-frontend, test-report, unit-audit-*）、Policy（design-fidelity, design-planning, task-decomposition）、Persona（architect-planner, research-*, conductor, test-planner, ai-antipattern-reviewer）。implement-e2e-test/plan-e2e-test removed
takt-analyzer	ムーブメント → ステップ、ピースYAML → ワークフローYAML terminology unified. Built-in reference path updated to workflows/ updated to
takt-optimizer	ムーブメント統合 → ステップ統合. All terminology unified to step/workflow . Reference path updated to workflows/ updated to

v0.29.0 → v0.31.0（2026-03-09）

Skills	Changes
All skills	前提 takt バージョン: v0.31.0 updated to
takt-task-builder	pr_failed added to status (6th terminal state) transition table
takt-workflow-builder	Built-in table refreshed to current piece list (expert/default-mini/review-only → dual/backend/frontend/review/takt-default etc.).allowed_tools → provider_options.claude.allowed_tools migration example added. Loop monitor's instruction unified to built-in facet references.takt-default-team-leader abolished (takt-default merged into)
takt-facet-builder	Built-in list greatly expanded (Instruction: dual-team-leader-implement, loop-monitor-reviewers-fix, team-leader-implement etc. added. Knowledge: task-decomposition added. Persona: supervisor, dual-supervisor etc. added. Output Contract: each review type added). Added to review output contract: family_tag/reopened section structure added
takt-analyzer	provider_options structure check items added.*-provider-events.jsonl(separate file) and trace.md log description added.observability → logging rename reflected
takt-optimizer	instruction reference normalization,allowed_tools の provider_options migration optimization item added

v0.29.0 → v0.30.0 (2026-03-06, unapplied → merged into v0.31.0)

Skills	Changes
All skills	前提 takt バージョン: v0.30.0 updated to
takt-task-builder	pr_failed status (6th terminal state) added. PR creation failure separated from failed .failure is optional (failed unlike, not required)
takt-workflow-builder	allowed_tools → provider_options.claude.allowed_tools moved to. Loop monitor's instruction unified to built-in facet references (loop-monitor-ai-fix, loop-monitor-reviewers-fix) . Added to design decision guide: provider_options added
takt-facet-builder	Added to built-in Instruction: loop-monitor-ai-fix, loop-monitor-reviewers-fix added. Added to review output contract: family_tag/new/persists/resolved/reopened section structure added
takt-analyzer	provider_options structure check items added.*-provider-events.jsonl(separate file) and trace.md log description added.observability → logging rename reflected
takt-optimizer	instruction Added optimization item for reference normalization

v0.22.0 → v0.29.0（2026-03-04）

Skill	Change details
All skills	前提 takt バージョン: v0.29.0 Added
takt-task-builder	exceeded Status (5th terminal state) added.base_branch, exceeded_max_movements, exceeded_current_iteration Field added
takt-workflow-builder	expert → dual Renamed (v0.28.1).default-mini Abolished.review-fix series /backend/frontend series piece added.quality_gates Field added
takt-facet-builder	No change
takt-analyzer	No change
takt-optimizer	provider-events.jsonl Added (minor)