AI Agent Playbook 1.3.0

한국어

• 선택형 --profile light를 추가했습니다. 짧은 project-notes 스킬 하나를 설치하며 별도 참고 자료가 없습니다.
• 프로필 전환 시 대체 스킬 설치가 실패하면 기존 스킬 제거를 차단합니다. 제거 직전마다 선택한 모든 설치본을 재확인하고 사용자 수정본과 복구 자료를 보존합니다.
• 일반 설치는 추가 방식이며 기존 설치를 줄일 때는 명시적인 migration을 사용합니다. 부트스트랩은 기존 --records minimal을 사용합니다.
• 전체 테스트 307개, 필수 검사, 배포 archive CLI·전환·복구·실패 보존, MCP 도구 4개 호출과 문서 링크 256개를 확인했습니다.
• GitHub Actions의 Windows·Ubuntu 검사도 통과했습니다.

한국어 릴리스 안내

English

• Add the optional --profile light, selecting one compact project-notes skill without a reference bundle.
• Guard profile migration cleanup on valid selected replacements. Failed or changed replacements block remaining removals; ownership checks, local edits, and recovery journals are preserved.
• Ordinary installation remains additive. Reducing an existing installation requires explicit migration. Bootstrap retains its existing --records minimal choice.
• Validation includes 307 tests, required checks, packaged CLI installation/migration/recovery/failure preservation, four MCP tool calls, and 256 documentation links.
• GitHub Actions validation passed on Windows and Ubuntu.

English release notes

Package and usage

The attached archive and SHA-256 file are the verified release artifacts. GitHub release publication and npm registry publication are separate; use the attached archive until version 1.3.0 is available in npm.

After npm publication:

npm install -g ai-agent-playbook@1.3.0
ai-agent-playbook skills install --profile light --dry-run --json

For an existing installation:

ai-agent-playbook skills migrate --profile light --json
ai-agent-playbook skills migrate --profile light --apply --json

Inspect the removal plan and retain its backup. Light changes the selected guidance bundle; it does not change permissions, required disclosures, provider logs, or company audit settings, and does not guarantee token or cost savings.

AI Agent Playbook 1.2.2

설치를 더 쉽게 안내하고 실제 프로젝트에서 확인한 기록 검색·경로 처리 문제를 수정한 패치 릴리스입니다. 기존 기록과 프로젝트 지침을 보존하며, 인자형 설치와 자동화도 계속 지원합니다.

한국어

설치 안내

• 처음 설치할 때 프로젝트·상위 폴더의 배치와 기록이 생성될 위치를 먼저 보여줍니다.
• 여러 저장소는 체크박스, 방향키·번호로 선택합니다. 검색, 다시 탐색, 뒤로 가기와 최종 설정 수정도 지원합니다.
• 권장 항목과 현재 설정을 구분합니다. 단일 선택에서 Enter만 눌러 기본값이 확정되지 않습니다.
• q 취소 안내와 조작 방법을 목록 위에 표시하고 한국어·영어 문구를 다듬었습니다.
• info/exclude는 Git 저장소 밖에서도 항목을 표시하고 사용할 수 없는 이유를 설명합니다. 실제 Git 저장소와 worktree를 기준으로 사용 가능 여부를 판단합니다.
• 대화형 설치 결과는 선택한 언어로 읽기 쉽게 표시합니다. --json, 명시적 인자와 --yes의 기존 동작은 유지합니다.

오류 수정

• 작업 기록 검색에 README·index·요약문이 섞이는 문제를 수정했습니다. 사용자 지정 작업 기록 폴더에도 적용됩니다.
• Windows에서 경로의 대소문자 때문에 기록 검색이 누락되는 문제를 수정했습니다.
• AST의 보호 폴더 제외를 대소문자 변경으로 우회할 수 없게 했습니다.
• 작업 기록 목록과 월 검색의 날짜 판정을 일치시켰습니다. 날짜가 없는 파일명도 유효한 createdAt 메타데이터로 월을 찾으며, 다른 월을 미리 제외하는 동작과 검색 한도는 유지합니다.

검증과 사용

Windows 로컬 테스트 295개와 필수 검사, 실제 터미널의 12개 저장소 선택, 두 기존 저장소의 CLI·SDK MCP 재검증을 완료했습니다. 격리 npm 1.2.1 → 1.2.2 → 1.2.1 설치·복구, 선택 의존성 누락, 배포 문서 링크와 파일 구성을 확인했습니다. 기존 프로젝트 파일과 Git 상태를 보존했습니다. GitHub의 Windows·Ubuntu CI도 모두 통과한 뒤 병합했습니다.

ai-agent-playbook bootstrap
ai-agent-playbook bootstrap --interactive --dry-run

GitHub 첨부 압축 파일은 검증한 npm 배포물이며 SHA256SUMS.txt로 확인할 수 있습니다. MCP의 자동 도구 선택, 제품 UI 전체 동작과 전역 설치 갱신은 이 검증과 별개입니다.

English

This patch improves guided setup and fixes record-search and path-handling issues found in existing projects, while preserving records, project instructions and automation interfaces.

• Show folder preparation and the intended record location before creating files. Select repository checkboxes with arrows or numbers; search, rescan, go back and edit settings during final review.
• Separate recommendations from saved settings. Single-choice menus require an explicit selection, and cancellation help appears above the list.
• Keep local info/exclude visible with an availability reason outside Git. Resolve the actual containing Git worktree, including linked worktrees.
• Improve English/Korean menu wording and readable interactive results. Preserve explicit arguments, JSON output and --yes behavior.
• Exclude guides and summaries consistently from worklog search, including custom folders; fix Windows record-path casing and AST protected-directory case aliases.
• Align monthly search with worklog listing on filename, folder and metadata dates while retaining scan limits and pruning other months.

Validation includes 295 local Windows tests, required checks, a live twelve-repository terminal flow, CLI/SDK MCP checks in two existing repositories, isolated npm upgrade and recovery, optional-dependency failure handling, package contents and documentation links. GitHub Windows and Ubuntu CI also passed before merge. SDK invocation does not establish automatic tool selection in a fresh host or every application UI behavior.

The attached npm archive and checksum file are the verified release artifacts. Updating a global installation and publishing to npm are separate operations.

AI Agent Playbook 1.2.1

한국어

1.2.0의 Windows 경로 보호를 보완한 패치입니다.

• Windows의 짧은 경로를 실제 경로로 확인한 뒤 제외 범위를 검사합니다. 전역 제외 파일이 Git 메타데이터·프로젝트 기록·지침 또는 다른 제외 파일과 겹치는 설정을 차단합니다.
• 링크 거부를 유지하며, 아직 없는 제외 파일 경로와 기존 복구 기록의 동등한 경로를 지원합니다.
• Windows 시험 경로를 정규화하고 시험용 PowerShell 보조 호출의 대기를 보완했습니다. 제품의 대기 제한과 보호 조건은 유지합니다.

로컬 전체 테스트 242개, Windows·Ubuntu PR CI, 설치본의 기록·AST·MCP, 1.2.0→1.2.1→1.2.0 복구를 검증했습니다. 병합된 소스는 검증한 PR 소스와 같은 파일 내용을 갖습니다.

npm install -g ai-agent-playbook@1.2.1

MCP 연결은 패키지 갱신 후 다시 불러오세요. 1.2.0 대비 스킬 내용과 기록 형식은 바뀌지 않습니다. 1.1에서 올라오는 경우에는 1.2.0 사용·이전 안내도 참고하세요.

English

This patch fixes the Windows exclusion-boundary issue identified in 1.2.0.

• Resolve short-path aliases before checking whether an ignore file overlaps Git metadata, project records, instructions or another exclusion scope.
• Retain link rejection while supporting new ignore-file paths and equivalent paths in existing recovery journals.
• Normalize Windows test paths and allow enough time for the test-only PowerShell helper. Product timeouts and protection assertions remain intact.

Validation includes 242 local tests, Windows/Ubuntu PR CI, installed-package records/AST/MCP, and record-preserving upgrade and rollback from 1.2.0 to 1.2.1 and back. The merged tree matches the tested PR tree.

Install with the command above and reconnect MCP after updating. Skill contents and record formats are unchanged from 1.2.0. Users upgrading from 1.1 should also follow the 1.2.0 migration notes.

Package

ai-agent-playbook@1.2.1 is published on npm with the latest tag. The attached archive matches the registry file byte-for-byte. npm의 정식 1.2.1 및 latest 게시와 첨부 파일 일치를 확인했습니다.

SHA-256: c14bc64e73fb200c61d16c9bf84759e44a1fe970759cd9ddfea03a251bb62578

Full changelog / 전체 변경

AI Agent Playbook 1.2.0

한국어

AI Agent Playbook 1.2는 Git 없는 설치, 다중 저장소의 공통 기록, 월별 worklog와 업무 지식을 지원합니다. 하나의 제품이 웹·백엔드·여러 모바일 저장소로 나뉘어 있어도 상위 폴더에 기록을 모으고, 등록된 하위 저장소에서 같은 맥락으로 작업을 이어갈 수 있습니다.

왜 바꿨나요?

1.0에서는 모델과 겹치는 일반 작업 절차를 줄이고 기록·규격·실행 도구에 집중했습니다. 1.2에서는 실제 사용에서 드러난 다중 저장소의 대상 구분과 기록 복구의 빈틈을 보완했습니다. 지침 수나 문서 길이 자체를 줄이기보다 필요한 근거를 보존하고 관련 범위부터 찾도록 만드는 것이 목적입니다. Astra와 Sol 모두 주 작업 모델로 사용할 수 있으며 사용자의 모델·추론 설정을 강제하지 않습니다.

주요 변경

• 설치: 옵션 없는 터미널 실행은 대화형 안내를 제공합니다. 기존 인자형 자동화와 --interactive, --yes, --dry-run, --json을 함께 지원합니다. Git이 없어도 기록을 생성하며 git init을 자동 실행하지 않습니다.
• 제외·복구: local은 Git의 info/exclude, shared는 .gitignore, global은 사용자 Git 제외 파일, none은 제외 없음입니다. --local-only는 호환 인자로 유지합니다. 사용자 규칙과 추적 파일은 보존하고, 관리된 변경은 백업·검사 후 적용하거나 복구합니다.
• 작업 공간: workspace list/add/remove/check로 저장소를 명시적으로 등록합니다. 등록된 하위 저장소에서 공통 기록을 찾고, 기존 개별 기록은 recordSource/--record-source로 선택합니다. 등록 제거는 코드나 기록을 삭제하지 않습니다.
• 기록: worklog new/list, knowledge new를 추가했습니다. 새 작업 기록은 월별 폴더와 고유 파일명을 사용합니다. 현재 목표는 CURRENT.md, 현재 유효한 업무 규칙은 knowledge, 판단 과정과 검증 근거는 worklog에 둡니다. 과거 대화를 자동 수집하거나 가정을 사실로 바꾸지 않습니다.
• 검색·대상 보호: 경로·월·종류·저장소 필터와 페이지 이어 읽기를 제공합니다. AST·Forge는 현재 저장소 또는 --repo를 사용하며, 상위 폴더에서 대상이 모호하면 선택을 요구합니다. 일반 하위 폴더가 상위 Git 원격을 잘못 물려받지 않도록 막습니다.
• 지침·문서: 개인·프로젝트 AGENTS와 기록 스킬을 한영으로 보완했습니다. README 로고·언어별 구성·초보자 안내·상세 명령 예제를 유지했습니다. Node와 Python의 버전 표기도 1.2.0으로 맞췄습니다.

설치와 업그레이드

npm install -g ai-agent-playbook@1.2.0
ai-agent-playbook --version
ai-agent-playbook skills update --profile development --dry-run
ai-agent-playbook skills update --profile development

스킬 갱신은 미리보기 결과를 확인한 뒤 적용하세요. npm 패키지 설치만으로 스킬이나 MCP가 자동 등록되지는 않습니다. ai-agent-playbook이 기본 명령이며 aapb는 같은 구현의 짧은 별칭입니다. 프로젝트 경로를 생략하면 현재 터미널 폴더를 사용합니다.

새 설치는 프로젝트 폴더에서 ai-agent-playbook bootstrap으로 시작합니다. 기존 설치에서는 문서를 다시 생성하거나 레이아웃을 강제로 옮기지 않습니다. Git 제외는 이미 추적 중인 파일을 숨기지 않습니다. 공통 기록이 하위 Git 저장소 밖에 있으면 각 하위 저장소에 제외 규칙을 추가할 필요가 없습니다.

MCP는 기본 기록 도구 네 개와 선택형 mcp --with-ast의 AST 도구 하나를 유지합니다. 개발 프로필은 스킬 다섯 개이며 선택형 레거시 계약을 포함한 소스 스킬은 여섯 개입니다. 기존 MCP 이름·허용 도구 수는 바뀌지 않습니다. 새 패키지 사용 후 MCP 연결을 다시 불러오세요. Kotlin·Swift AST 언어는 이번에 추가하지 않았습니다.

검증과 한계

1.2.0에서 확인된 제한: Windows의 짧은 경로를 사용해 core.excludesFile이 Git 메타데이터나 프로젝트 기록·지침 파일을 가리키도록 설정하면 겹침 보호가 누락될 수 있습니다. 이러한 파일을 제외 파일로 지정하지 마세요. 실제 경로로 확인하는 수정과 회귀 검증을 1.2.1 패치로 분리했으며, 이 릴리스의 1.2.0 첨부 파일에는 그 후속 수정이 포함되지 않습니다.

• 기능 후보에서 Windows Node 22 전체 테스트 240개를 통과했습니다. 정식 버전 전환에서는 버전·CLI·Forge HTTP 관련 15개와 Python·한영 문서 검사를 추가로 확인했습니다. 이를 255개의 서로 다른 전체 테스트로 합산하지 않습니다.
• 독립 Git 저장소 12개, 실제 한국어 터미널의 취소·미리보기, SDK MCP·AST, 실제 Codex의 Astra xhigh·Sol max 기록 기반 재개를 검증했습니다.
• 정식 압축 파일로 1.1.0 → 1.2.0 → 1.1.0 복구를 시험하고 기록 보존을 확인했습니다. AST 선택 의존성 없는 설치에서도 기록 기능이 동작합니다.
• 짧은 기록 세 사례에서는 Sol 초안 작성 후 Astra 검토를 합친 시간과 입력량이 메인 단독보다 늘었습니다. 일반 기록은 메인이 작성하고 긴 독립 정리만 선택적으로 위임합니다. 일반적인 토큰·구독 비용 절감률을 주장하지 않습니다.
• 이번 로컬 검증에는 실제 업무 저장소, 네이티브 기기, Node 18 실행이나 긴 기록 위임의 비용 효과가 포함되지 않습니다. 원격 쓰기는 시험용 전송으로 검증했습니다.

명령 가이드 · 다중 저장소 · 기록 관리 · 복구

English

AI Agent Playbook 1.2 adds Git-less setup, shared records across explicitly registered repositories, monthly worklogs, and durable topic knowledge. A workspace can keep its records above separate web, backend and mobile repositories, and registered members can resume from that shared context.

Why this release?

Version 1.0 focused AAPB on portable records, artifact formats and concrete tools instead of duplicating general agent procedures. Version 1.2 addresses practical gaps in repository targeting and record continuity. The objective is to preserve useful evidence and retrieve relevant scope first, rather than minimize instruction counts or document length. Astra and Sol can both be main models; user model and reasoning choices remain intact.

What changed

• Interactive bootstrap and existing argument-based automation share the same implementation. Git is optional; setup never initializes it automatically. Preview and cancellation do not write files.
• Choose local Git info/exclude, shared .gitignore, global Git exclusions or no exclusions. Preserve user rules and tracked files; inspect, back up and recover managed changes. --local-only remains compatible.
• Explicit workspace registration supports list/add/remove/check, ancestor discovery from members and separate access to existing member-local records. Removing membership never deletes code or history.
• Create/list monthly worklogs and create topic knowledge. Keep current goals in CURRENT.md, current rules in knowledge, and decisions plus exact verification evidence in worklogs. No automatic conversation collection or factual promotion of assumptions.
• Filter records by path, repository, month and kind, with bounded continuation. AST and Forge require one selected code repository; a plain subdirectory cannot inherit an ancestor remote for workspace operations.
• Update English/Korean personal and project instructions, record skills and detailed guides while preserving README branding and language-specific presentation. Align Node and Python version metadata at 1.2.0.

Upgrade and compatibility

Use the installation commands above, previewing skill updates before applying them. Package installation does not register skills or MCP automatically. ai-agent-playbook remains the primary executable and aapb its alias; omitted project paths use the current directory. Start a new setup with ai-agent-playbook bootstrap. Existing documents and layouts remain intact unless an explicit supported change is applied.

The MCP surface remains four default record tools plus one optional AST tool with mcp --with-ast. Reconnect after the package update. The development profile still selects five skills; six are available including optional legacy contracts. Kotlin and Swift AST support was not added. Git exclusions do not untrack existing files, and shared records outside member repositories need no per-member exclusion rule.

Validation scope

Known 1.2.0 limitation: Windows short-path aliases can evade the overlap guard when core.excludesFile is configured to point at Git metadata, project records or instructions. Do not designate those files as ignore files. Canonical-path validation and regressions are prepared as a separate 1.2.1 patch; the original 1.2.0 attachment does not contain that follow-up fix.

The functional candidate passed 240 Windows/Node 22 tests. Stable promotion separately passed 15 focused version/CLI/Forge HTTP tests, Python validation and English/Korean documentation checks. These are not 255 distinct full-suite tests. Validation also covered twelve independent Git repositories, actual terminal cancellation/previews, SDK MCP/AST, and real Codex record resumption using Astra xhigh and Sol max.

The stable archive passed isolated installation, record-preserving upgrade and rollback from 1.1.0 to 1.2.0 and back, including record functionality without the optional AST dependency. Three small writing comparisons found greater total time and input usage for Sol drafting plus Astra review than for the main model alone. Ordinary records therefore remain with the main task; long independent drafts are optional. No general token or subscription-cost savings are claimed.

The local validation did not exercise production repositories, native devices, Node 18 execution or long-record delegation economics. Remote-write tests used test transports.

Command guide · Workspaces · Durable records · Recovery

Package

ai-agent-playbook@1.2.0 is published on npm with the latest tag. The attached archive is byte-for-byte identical to the registry archive. npm의 정식 1.2.0 및 latest 게시와 첨부 파일의 일치를 확인했습니다.

SHA-256: 0470271c84bb6c4eeac26e6b143c446f334ba10a19b71d7461a95f64663ec595

Full changelog / 전체 변경

AI Agent Playbook 1.1.0

한국어

1.0의 작은 스킬·기록 구성을 유지하면서 읽기 전용 AST 구조 검색을 복원했습니다. 코드를 파싱하는 검색 도구는 반복적인 작업 절차 지침과 구분해 필요한 기능으로 제공합니다.

• ai-agent-playbook ast search: 언어와 프로젝트 상대 경로를 선택해 구조 패턴을 검색합니다.
• mcp --with-ast: 기존 기록 도구 네 개에 aapb_ast_search 하나를 추가합니다. 개발 스킬은 다섯 개를 유지합니다.
• 선택 네이티브 엔진을 호출할 때만 로딩하고, 소스 위치·검색 범위·결과 페이지를 제공합니다.
• 원본이 바뀐 커서와 링크 경로를 거부하며, 파서 실패를 정규식 결과로 바꾸지 않습니다.
• 스킬 재설치나 기록 이전은 필요하지 않습니다. AST를 MCP에서 쓰려면 시작 인자와 도구 허용 목록을 한 번 갱신하고 연결을 다시 불러옵니다.

Windows·Ubuntu GitHub CI, Node 22 전체 테스트 154개, Node 18 AST·MCP 16개, 패키지 일반/선택 엔진 제외 설치와 두 실제 프로젝트의 CLI·SDK 검색을 검증했습니다. 자동 도구 선택과 속도·토큰 개선을 입증하는 결과는 아닙니다.

npm의 ai-agent-playbook@1.1.0과 latest 게시를 확인했습니다. 레지스트리 압축 파일은 첨부한 검증본과 SHA-256이 일치합니다.

한국어 사용법

English

Restore read-only structural source search while retaining the small 1.0 skill and record setup. Concrete parsing capabilities are evaluated separately from duplicated workflow instructions.

• Use ai-agent-playbook ast search with an explicit language and project-relative source scope.
• Opt in once with mcp --with-ast to add aapb_ast_search; the default four record tools and five development skills stay unchanged.
• Load the optional native engine only for AST calls, with bounded results, source positions, continuation and coverage reporting.
• Reject linked paths and changed-source cursors; never substitute regex output for a parser failure.
• No skill reinstall or record migration is required. Update the MCP startup arguments and any explicit tool allowlist, then reconnect to enable AST.

Validation includes Windows/Ubuntu GitHub CI, 154 Node 22 tests, 16 focused Node 18 AST/MCP tests, installations with and without the optional engine, and matching CLI/SDK searches in two existing projects. These checks do not prove universal host selection or speed/token improvements.

ai-agent-playbook@1.1.0 is published on npm and tagged latest. Its registry archive matches the attached verified artifact by SHA-256.

English usage and recovery

AI Agent Playbook 1.0.0

AI Agent Playbook 1.0.0

1.0 centers AAPB on project records, requested artifact formats, and selected specialist guidance. Coding agents and project tools remain responsible for implementation and execution.

Why we redesigned AAPB

The starting point for 1.0 was the growing capability of coding models. Earlier versions of AAPB supplied extensive skills, prescribed workflows, and execution features to support their work. As models became better at planning, exploring repositories, using tools, and reviewing changes, we reconsidered which parts of that support still added value.

We judged that overlapping instructions and procedures could make the harness itself a bottleneck for more capable models. Rereading similar guidance, resolving competing process rules, and repeating checks already provided by the host can consume context and execution time without moving the project forward.

AAPB 1.0 therefore gives models and their hosts room to handle general work, while retaining the context they cannot reliably reconstruct: project decisions and evidence, product constraints, requested artifact formats, and specialist contracts. Design, UI, and Korean/English writing guidance remain available where they add value. Detailed references are selected for the task, and routine execution stays with the host and project tools.

Main changes

• Use ai-agent-playbook as the primary command or aapb as its equivalent short alias. Project commands use the current directory when the path is omitted.
• Start new project records with CURRENT.md and two metadata files. Read existing layouts without forcing a migration.
• Select core, development, legacy, or individual skills. The catalog has six skills; the development profile selects five.
• Install into one default skill root, preserve modified or unmanaged content, and use explicit migration previews and recovery journals.
• Optionally connect aapb_status, aapb_search, aapb_read, and aapb_validate. Long results support continuation and adjustable content budgets.
• Use optional writing/UI checks and reviewed GitHub/Gitea coordination when relevant.
• Adapt neutral project instructions and fuller personal defaults. Architecture belongs to each project and can evolve through explicit decisions.
• Follow complete English and Korean beginner, command, migration, and maintenance guides.

Before updating from 0.5

The earlier executor, supervisor, scheduler, automatic delivery, and broad analysis commands are retired. They return a retirement message and a pinned 0.5.11 recovery hint; they do not run the old runtime automatically. Existing schedules and remote records are not rewritten.

Skill installation, CLI installation, project bootstrap, and MCP registration remain separate. Updating the npm package does not replace personal/project AGENTS.md, change model settings, or enable integrations. If old owned skill copies remain in two roots, preview skills migrate and preserve its recovery data.

For previous behavior, use npx ai-agent-playbook@0.5.11 --help. The old global executable is aapb. See the changes and previous-version guide and installation/recovery.

Install the published release

npm install -g ai-agent-playbook@1.0.0
ai-agent-playbook --version
aapb --version
ai-agent-playbook records status --json

Run the last command from a project directory. An absent playbook is a normal first-use result. Follow First 10 minutes to create records and the command guide for full option combinations.

Verification scope

Use the exact release archive and its checksum when verifying installation. Record tests, SDK MCP calls, host discovery, and application behavior separately. Document validation does not run application tests. Historical results and bounded model comparisons are preserved in the verification record; they do not establish universal performance gains.

Publishing checklist explains npm/GitHub delivery and registry verification. Agent use explains how to verify actual skill and tool use in a host.

---

AI Agent Playbook 1.0.0

1.0은 프로젝트 기록, 요청한 산출물 형식과 필요한 전문 지침에 집중합니다. 구현과 실행은 코딩 에이전트와 프로젝트의 도구가 맡습니다.

왜 AAPB를 개편했나요?

1.0 개편의 출발점은 코딩 모델의 성능 향상이었습니다. 이전 AAPB는 많은 스킬과 정해진 작업 절차, 실행 기능으로 모델의 작업을 보조했습니다. 모델이 계획, 저장소 탐색, 도구 사용, 변경 검토를 더 잘 수행하게 되면서 이 중 어떤 부분이 여전히 도움이 되는지 다시 살펴봤습니다.

모델 성능이 높아진 환경에서는 지침과 절차의 중복이 오히려 하네스 자체를 병목으로 만들 수 있다고 판단했습니다. 비슷한 지침을 반복해서 읽고, 서로 다른 절차 규칙을 조율하고, 사용 중인 앱이 이미 제공하는 검사를 되풀이하면 실제 작업을 진전시키지 못한 채 문맥과 실행 시간을 쓰게 됩니다.

이에 1.0은 일반적인 작업을 모델과 실행 환경에 맡기고, 모델이 스스로 정확히 복원하기 어려운 프로젝트 결정과 근거, 제품 제약, 요청한 산출물 형식, 분야별 계약에 집중합니다. 디자인·UI·한국어와 영어 문서 작성 지침도 도움이 되는 부분을 남겼습니다. 상세 참고 자료는 작업에 맞게 선택하고, 일상적인 실행은 사용 중인 앱과 프로젝트 도구가 맡도록 역할을 정리했습니다.

주요 변경

• 기본 명령 ai-agent-playbook과 같은 기능의 축약 명령 aapb를 제공합니다. 프로젝트 경로를 생략하면 현재 폴더를 사용합니다.
• 새 프로젝트 기록은 CURRENT.md와 관리 파일 두 개로 시작합니다. 기존 구조는 강제로 이전하지 않고 읽을 수 있습니다.
• core, development, legacy 또는 개별 스킬을 선택합니다. 스킬은 여섯 개이며 개발 프로필은 다섯 개를 고릅니다.
• 기본 스킬 설치 위치를 하나로 통일합니다. 수정본과 미관리 파일을 보존하고 명시적인 이전 미리보기와 복구 일지를 제공합니다.
• aapb_status, aapb_search, aapb_read, aapb_validate를 선택해서 연결합니다. 긴 결과는 이어 읽기와 본문 크기 조절을 지원합니다.
• 문서·UI 점검과 검토한 GitHub/Gitea 협업 기능을 필요할 때 사용합니다.
• 중립 프로젝트 지침과 보강한 개인 기본 지침을 제공합니다. 아키텍처는 각 프로젝트가 결정하고 필요에 따라 바꿉니다.
• 영어·한국어 초보자, 명령어, 이전과 유지보수 안내를 제공합니다.

0.5에서 갱신하기 전에

이전 실행기, 감독기, 예약기, 자동 전달과 광범위 분석 명령은 종료했습니다. 실행하면 종료 안내와 0.5.11 버전 고정 복구 방법을 보여주며 구버전을 자동 실행하지 않습니다. 기존 예약과 원격 기록도 자동으로 바꾸지 않습니다.

스킬 설치, CLI 설치, 프로젝트 기록 생성과 MCP 등록은 각각 별도 작업입니다. npm 패키지를 갱신해도 개인·프로젝트 AGENTS.md, 모델 설정이나 연동 활성 상태가 바뀌지 않습니다. 두 경로에 구버전 관리 스킬이 남아 있다면 skills migrate를 미리 보고 복구 자료를 보관하세요.

이전 동작이 필요하면 npx ai-agent-playbook@0.5.11 --help를 사용합니다. 구버전 전역 명령은 aapb입니다. 변경사항과 이전 버전 안내, 설치·복구를 참고하세요.

게시된 정식 버전 설치

npm install -g ai-agent-playbook@1.0.0
ai-agent-playbook --version
aapb --version
ai-agent-playbook records status --json

마지막 명령은 프로젝트 폴더에서 실행합니다. 처음에는 플레이북이 없다는 결과가 정상일 수 있습니다. 기록 생성은 처음 10분, 전체 옵션 조합은 명령어 가이드를 참고하세요.

검증 범위

설치 검증에는 정확한 릴리스 압축 파일과 체크섬을 사용합니다. 기록 테스트, SDK MCP 호출, 앱의 도구 발견과 제품 동작을 구분해 기록합니다. 문서 검증은 애플리케이션 테스트를 실행하지 않습니다. 이전 결과와 제한된 모델 비교는 검증 기록에 보존하며 보편적인 성능 향상을 뜻하지 않습니다.

npm·GitHub 게시와 레지스트리 확인은 배포 점검표, 앱에서 스킬과 도구의 실제 활용을 확인하는 방법은 에이전트 활용 안내에 있습니다.

v0.5.11

주요 변경

• 기존 AGENTS.md가 있는 저장소에서 보존·연결·명시적 교체 방식을 선택할 수 있도록 bootstrap 계약을 확장했습니다.
• .gitignore의 기존 내용, UTF-8 BOM, 줄바꿈 형식과 마지막 개행을 유지하면서 playbook 항목만 멱등적으로 추가합니다.
• qa ui-genericity-scan과 generic-ui-review 스킬을 추가해 템플릿처럼 보일 수 있는 UI 패턴을 읽기 전용 후보로 검토합니다.
• writing fidelity-check를 추가해 문서 수정 전후의 수치·버전·URL·명령·경로·식별자·문체 이동을 증거로 비교합니다.
• 한국어 개발 문서 자연스러움 검사를 반복·밀도·문맥 중심으로 보강하고 JS/Python 중복 보고를 줄였습니다.

업그레이드 주의

• 기존 AGENTS.md가 있으면 명시적 모드 없이는 이전과 같이 쓰기 전에 중단합니다.
• 제품별 작업 규칙을 그대로 둘 때는 --preserve-agents, playbook 읽기 순서만 연결할 때는 --link-agents를 사용하세요.
• 전체 교체는 --replace-agents --force를 함께 지정한 경우에만 허용됩니다. --force만으로는 기존 파일을 덮어쓰지 않습니다.
• 기존 manifest schema는 읽기 호환되며 별도 강제 마이그레이션은 필요하지 않습니다.

검증

• 로컬 및 병합 후 테스트: 459건 중 458건 통과, Windows symlink 권한 테스트 1건 skip, 실패 0건
• 문법, TypeScript, Python engine, 스킬 94개, 번역 382개, MCP/public docs 검증 통과
• GitHub Actions push/PR 검증 2건 통과
• npm pack dry-run: 507파일, _reference·_work·로컬 playbook/runtime 포함 0건

v0.5.10

주요 변경

• Hosted GitHub/Gitea workflow의 automation start와 automation tick이 현재 package release를 정확히 사용하도록 version source를 단일화했습니다.
• Forge REST User-Agent와 Node/Python release metadata를 0.5.10으로 정렬했습니다.
• Windows에서 python3 alias가 동기적으로 실패해도 정상 interpreter 후보 탐색을 계속하도록 복구했습니다.
• 영문·한국어 Actions template, runtime/command 문서, 업그레이드 지침을 함께 갱신했습니다.

업그레이드 주의

• 기존 run ledger, plan, checkpoint, 권한, repository variable, kill switch migration은 필요하지 않습니다.
• 다른 프로젝트에 이미 복사한 hosted workflow는 자동으로 덮어쓰지 않습니다. 최신 template 또는 schedule preview를 검토한 뒤 start/tick의 ai-agent-playbook@... pin 두 곳을 0.5.10으로 갱신하세요.

검증

• 로컬 전체 테스트 447개 통과
• 문법, TypeScript, Python engine, 스킬, 번역, MCP/public docs 검증 통과
• GitHub Actions push/PR/main 검증 통과
• npm pack dry-run: 0.5.10, 필수 runtime 파일 포함, 내부·테스트 경로 제외

AI Agent Playbook 0.5.9

주요 변경

• automation resume --reset-attempts 이후 과거 attempt 이벤트 ID를 재사용하던 결함을 수정했습니다.
• 재시도 예산 attempts와 append-only claim serial attemptSerial을 분리했습니다.
• 기존 schema v2 ledger는 변환하거나 덮어쓰지 않고 task.claimed 이벤트 재생으로 serial을 복원합니다.
• 실패 3회 후 reset한 다음 tick이 attempt:4를 기록하는 회귀 테스트를 추가했습니다.
• package/Python metadata와 한영 명령·runtime·recovery 문서를 0.5.9로 갱신했습니다.

호환성

• 기존 0.5.8 run ID와 ledger를 그대로 사용할 수 있습니다.
• event ID 충돌 회피만을 위해 새 run을 만들 필요가 없습니다.
• reset 전 실패 evidence를 검토한 뒤 명시적으로 --reset-attempts를 사용해야 합니다.

검증

• npm test: 445개 통과
• npm run check
• npm run typecheck
• npm run validate:python
• npm run validate:all
• PowerShell skill/translation validation과 sync dry-run
• npm pack --dry-run --json

npm 패키지는 별도 발행 절차가 필요합니다.

AI Agent Playbook 0.5.8

Forge Idempotent Reconcile 0.5.8

AI Agent Playbook 0.5.8 makes presentation reconciliation report and write only meaningful remote changes.

Provider-confirmed preview

• forge reconcile now runs the planned operations through the real provider adapter behind a read-only transport.
• Operations proven to be reusable are removed from the executable preview and reported as noOps; any operation that reaches a write boundary remains planned.
• Artifact counts follow the filtered operation set, while plannedOperations retains the original intent count for auditability.

Project convergence

• A missing GitHub Project text field and an explicitly empty desired value are treated as equivalent, matching GitHub's omission of empty text values from item responses.
• A Project's system-created View 1 can satisfy the managed all role, preventing an additional duplicate table view. GitHub's stable public View API creates views but does not rename or delete the system view, so the harness does not claim that the visible name was changed.
• Existing user views and Project items are never deleted by this convergence pass.

Legacy managed-body migration

• Reviewed presentation reconcile can replace an old generated objective and acceptance preamble that sits immediately before the managed block.
• Migration is limited to the strict legacy marker shape and CAS-protected issue snapshot. User text outside that shape and text after the managed block remain preserved.