pactkit 2.0.2__tar.gz → 2.1.1__tar.gz

{pactkit-2.0.2 → pactkit-2.1.1}/.gitignore

@@ -43,3 +43,4 @@ docs/architecture/snapshots/
 *.bak
 .mcp.json
 coder/
+docker/

pactkit-2.1.1/.opencode/memory/.gitignore

@@ -0,0 +1 @@
+*

pactkit-2.1.1/.opencode/memory/project.md

@@ -0,0 +1,41 @@
+---
+description: PactKit project-specific knowledge — architecture, patterns, release process, and key decisions.
+label: project
+limit: 5000
+read_only: false
+---
+## Project
+- PactKit: Spec-driven agentic DevOps toolkit
+- Version: 2.1.0 (released 2026-03-17, PyPI + GitHub Release)
+- Test Count: 2307+ (grew +113 in one day from 2194)
+- Stack: Python 3.10+, hatchling build, pyyaml only runtime dep
+
+## Key Architecture (v2.1.0)
+- `profiles.py`: FormatProfile frozen dataclass registry (OCP: new format = one entry)
+- `schemas.py`: Document structure single source of truth (Spec/Board/Context/Lessons/TestCase)
+- `deployer.py`: `_render_prompt(template, profile)` — sequential str.replace for template vars
+- `config.py`: re-exports from profiles (VALID_FORMATS, PACTKIT_YAML_CANDIDATES, get_profile)
+- VALID_* sets in config.py are source of truth for component counts
+- CLAUDE_MD_TEMPLATE auto-generated from sorted(RULES_FILES.values())
+
+## Template Variables (11 total)
+- {SKILLS_ROOT}, {BOARD_CMD}, {VISUALIZE_CMD}, {SCAFFOLD_CMD}
+- {PACTKIT_YAML}, {GLOBAL_CONFIG_DIR}, {PROJECT_CONFIG_DIR}
+- {INSTRUCTIONS_FILE}, {DISPLAY_NAME}, {GLOBAL_INSTRUCTIONS}
+- {CONTEXT_SECTIONS}, {LESSONS_ROW_FORMAT}, {M} (backtick escape)
+
+## Key Patterns
+- Standalone scripts (board.py, scaffold.py) cannot import pactkit — inline + source-of-truth comment
+- Plugin mode: _render_prompt(classic) then _rewrite_skills_prefix(_legacy_prefix)
+- Spec template uses TBD as Release placeholder; spec-lint E008 enforces at Act time
+- Edit tool auto-formatting changes quotes — use explicit strings in tests
+
+## Release Process
+- PyPI: python -m build && twine upload dist/*
+- GitHub: gh release create vX.Y.Z --title "..." --notes "..."
+- Sync: CHANGELOG, pyproject.toml, __init__.py, README, pactkit.dev
+
+## Lessons
+- Sequential str.replace > format_map (complex keys like {R1, R2} cause ValueError)
+- CI runners have no ~/.config/opencode/ — tests must handle gracefully
+- auto_merge_config_file adds ALL missing components — mock in selective deploy tests

pactkit-2.1.1/.opencode/pactkit.yaml

@@ -0,0 +1,110 @@
+# PactKit Configuration
+# Edit this file to customize which components are deployed.
+# Remove items from a list to disable them. Default: all enabled.
+
+version: "2.1.1"
+stack: python
+root: .
+developer: "slim"
+
+# Agents — AI role definitions
+agents:
+  - code-explorer
+  - product-designer
+  - qa-engineer
+  - repo-maintainer
+  - security-auditor
+  - senior-developer
+  - system-architect
+  - system-medic
+  - visual-architect
+
+# Commands — PDCA playbooks
+commands:
+  - project-act
+  - project-check
+  - project-design
+  - project-done
+  - project-hotfix
+  - project-init
+  - project-plan
+  - project-sprint
+  - project-clarify
+  - project-pr
+  - project-release
+
+# Skills — tool scripts
+skills:
+  - pactkit-board
+  - pactkit-doctor
+  - pactkit-draw
+  - pactkit-release
+  - pactkit-review
+  - pactkit-scaffold
+  - pactkit-status
+  - pactkit-trace
+  - pactkit-visualize
+  - pactkit-analyze
+
+# Rules — constitution modules
+rules:
+  - 01-core-protocol
+  - 02-hierarchy-of-truth
+  - 03-file-atlas
+  - 04-routing-table
+  - 05-workflow-conventions
+  - 06-mcp-integration
+  - 07-shared-protocols
+  - 08-architecture-principles
+
+# CI/CD — set provider to github or gitlab to generate pipeline config
+ci:
+  provider: github
+
+# Issue Tracker — set provider to github to link stories to issues
+issue_tracker:
+  provider: github
+
+# Hooks — safe, report-only hook templates (command-type only)
+hooks:
+  post_test_coverage: false
+  pre_commit_lint: false
+  pre_push_check: false
+
+# Lint — configure lint behavior in /project-done
+lint_blocking: false
+auto_fix: false
+
+# Virtual Environment — configure venv detection and paths
+venv:
+  auto_detect: true
+
+# Release — configure release automation behavior
+release:
+  github_release: true
+
+# Regression — configure impact-based test selection strategy
+regression:
+  strategy: impact
+  max_impact_tests: 50
+
+# Check — configure QA verification behavior
+check:
+  security_checklist: true
+  security_scope_override: none
+
+# Done — configure commit and lesson quality behavior
+done:
+  lesson_quality_threshold: 15
+
+# Agent Models — override default model per agent (inherit = use account default)
+agent_models:
+  code-explorer: haiku
+  product-designer: opus
+  qa-engineer: sonnet
+  repo-maintainer: sonnet
+  security-auditor: sonnet
+  senior-developer: sonnet
+  system-architect: opus
+  system-medic: haiku
+  visual-architect: sonnet

{pactkit-2.0.2 → pactkit-2.1.1}/AGENTS.md

@@ -29,30 +29,39 @@ pactkit init --format opencode -t /tmp/oc-preview
 
 ```
 src/pactkit/
-├── cli.py              ← CLI entry: pactkit init/update/version/upgrade
-├── config.py           ← pactkit.yaml load/validate/generate
+├── cli.py              ← CLI entry: pactkit init/update/version/upgrade/schema
+├── config.py           ← pactkit.yaml load/validate/generate + re-exports from profiles
+├── profiles.py         ← FormatProfile registry (OCP: new format = one entry)
+├── schemas.py          ← Document structure schemas (DRY: single source of truth)
 ├── utils.py            ← atomic_write() utility
 ├── generators/
-│   └── deployer.py     ← Core deployment orchestrator (classic/plugin/marketplace/opencode)
+│   └── deployer.py     ← Core deployment orchestrator (classic/opencode/plugin/marketplace)
 ├── prompts/            ← All prompt templates and constants
 │   ├── agents.py       ← 9 agent definitions
-│   ├── commands.py     ← 11 command playbooks
+│   ├── commands.py     ← 11 command playbooks (use {TEMPLATE_VAR} placeholders)
 │   ├── references.py   ← Reference checklists (SOLID/Security/Quality)
-│   ├── rules.py        ← Constitution rule modules + AGENTS.md template
-│   ├── skills.py       ← 10 skill definitions
+│   ├── rules.py        ← 8 rule modules + CLAUDE_MD_TEMPLATE (auto-generated from RULES_FILES)
+│   ├── skills.py       ← 10 skill definitions (use {TEMPLATE_VAR} placeholders)
 │   └── workflows.py    ← PDCA workflow prompts + LANG_PROFILES
-└── skills/             ← Skill script source files
+└── skills/             ← Skill script source files (deployed as standalone scripts)
     ├── board.py        ← Sprint board operations
-    ├── scaffold.py     ← File scaffolding
-    ├── spec_linter.py  ← Spec structural linter
+    ├── scaffold.py     ← File scaffolding + SPEC_TEMPLATE (inline copy, see schemas.py)
+    ├── spec_linter.py  ← Spec structural linter (imports from schemas.py)
     └── visualize.py    ← Code dependency graph (Mermaid)
 ```
 
+## Key Architecture Files
+- `profiles.py` — Add new tool format here. See `FormatProfile` docstring for template variables.
+- `schemas.py` — Add new document type here. See `SCHEMA_REGISTRY` for discovery.
+- `deployer.py` — `_render_prompt(template, profile)` resolves all `{VAR}` placeholders at deploy time.
+
 ## Project Governance
 - Specs are in `docs/specs/` — they are the source of truth
 - Sprint board: `docs/product/sprint_board.md`
 - Architecture graphs: `docs/architecture/graphs/`
-- Config: `.claude/pactkit.yaml` (PactKit deployment config)
+- Config: `.opencode/pactkit.yaml` or `.claude/pactkit.yaml` (auto-detected, OpenCode preferred)
 - Global rules: `~/.config/opencode/AGENTS.md` (loaded automatically by OpenCode)
+- Architecture principles: `~/.config/opencode/rules/08-architecture-principles.md`
 
 @./docs/product/context.md
+output MUST use Chinese

{pactkit-2.0.2 → pactkit-2.1.1}/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.1.1] - 2026-03-18
+
+### Added
+- **Lazy Rule Loading** (STORY-slim-009) — Rules split into always-load core (`01-core-protocol`, `02-hierarchy-of-truth`, `09-credential-safety`) and on-demand `@reference` layer (6 files loaded by AI via Read tool when needed). Reduces per-turn system prompt overhead by 62% (7200 → 2800 tokens).
+- `RULES_CORE_FILES`, `RULES_ONDEMAND_FILES`, `RULES_INSTRUCTIONS_CORE` constants in `rules.py` for layered rule management.
+- AGENTS.md now contains `@rules/xxx.md` reference index with lazy-loading instructions — mirrors Claude Code's `@import` behavior in OpenCode's architecture.
+
+### Changed
+- `_update_global_opencode_json()` writes individual core rule paths instead of `rules/*.md` glob. Preserves user's existing instructions via merge strategy.
+- `_deploy_agents_md_inline()` generates on-demand `@reference` index from `RULES_ONDEMAND_FILES`.
+
+### Fixed
+- `_update_global_opencode_json()` no longer overwrites user's existing `instructions` entries (merge instead of replace).
+
+## [2.1.0] - 2026-03-17
+
+### Added
+- **FormatProfile Abstraction** (STORY-slim-005) — Frozen dataclass registry (`profiles.py`) replaces scattered if-else format branching. Adding a new tool format requires only one registry entry. `VALID_FORMATS` and `PACTKIT_YAML_CANDIDATES` auto-generated from `FORMAT_PROFILES`.
+- **Prompt Template Variables** (STORY-slim-006) — 48 hardcoded env-specific paths replaced with 11 named placeholders (`{SKILLS_ROOT}`, `{BOARD_CMD}`, `{PACTKIT_YAML}`, etc.) resolved at deploy time by `_render_prompt(template, profile)`.
+- **Document Schema Registry** (STORY-slim-007) — New `schemas.py` centralizes all document structure rules (Spec sections, Board headers, context.md sections, lessons.md format). New CLI command `pactkit schema [type]` for rule discovery.
+- **Deploy Chain Parity** (STORY-slim-008) — `_deploy_opencode()` now reads `pactkit.yaml` for selective deployment, calls `auto_merge_config_file()`, `_cleanup_legacy()`, generates project-level `AGENTS.md`, prints MCP recommendations. `_generate_config_if_missing(format=)` is format-aware.
+- **Architecture Principles Rule** — New `08-architecture-principles.md` codifies 8 principles (SOLID, DRY, 12-Factor, Defense-in-Depth) derived from project practice. `CLAUDE_MD_TEMPLATE` auto-generated from `RULES_FILES`.
+- **Codex CLI Pre-Research** (STORY-slim-001) — Tool integration checklist (11 dimensions, 60+ checks) and Codex capability matrix completed. Integration specs (STORY-slim-002/003/004) ready.
+- **Daily Retro Skill** — Personal growth feedback loop with 6 dimensions (engineering, architecture, new skills, thinking patterns, process, career). Triggered by cross-day context.md detection.
+- **Docker Containers** — Isolated `claude-code` and `opencode` containers for clean deployment verification.
+
+### Fixed
+- **BUG-slim-001**: `/project-init` no longer creates `.claude/` directory in OpenCode environment. Environment detection moved before `pactkit init` call. Playbook paths now use `$SKILLS_PATH` variable.
+- **Config Priority**: `.opencode/` now takes precedence over `.claude/` in `pactkit.yaml` resolution (newer environment preferred).
+- **Scaffold Developer Prefix**: `create_spec`, `git_start`, `create_e2e` auto-inject developer prefix from `pactkit.yaml`.
+
+### Changed
+- `opencode_format` boolean parameter removed from `_deploy_agents()`, `_deploy_commands()`, `_deploy_skills()` — replaced by `profile: FormatProfile`.
+- `OPENCODE_SKILLS_PREFIX` constant removed — use `get_profile("opencode").skills_path_var`.
+- `CLAUDE_ONLY_FIELDS` hardcoded set replaced by `profile.excluded_agent_fields` (extensible per format).
+- `TRACE_PROMPT` converted from f-string to regular string for template variable compatibility.
+- Spec scaffold template now uses `TBD` as Release placeholder (enforced by spec-lint E008 at Act time).
+
+## [2.0.2] - 2026-03-16
+
 ## [1.6.9] - 2026-03-13
 
 ### Fixed

{pactkit-2.0.2 → pactkit-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.0.2
+Version: 2.1.1
 Summary: Spec-driven agentic DevOps toolkit for AI coding assistants
 Project-URL: Homepage, https://pactkit.dev
 Project-URL: Repository, https://github.com/pactkit/pactkit
@@ -209,8 +209,8 @@ PactKit supports two deployment formats:
 
 ```
 ~/.config/opencode/
-├── AGENTS.md                 <- Slim header (rules loaded via instructions)
-├── rules/                    <- 7 rule modules (loaded via opencode.json instructions)
+├── AGENTS.md                 <- On-demand @reference index (lazy rule loading)
+├── rules/                    <- 8 rule modules (3 core always-load + 5 on-demand)
 ├── commands/                 <- 11 command playbooks (with model: routing)
 ├── agents/                   <- 9 agent definitions (mode: subagent)
 ├── skills/                   <- 10 skill packages (with SKILL.md frontmatter)
@@ -218,7 +218,7 @@ PactKit supports two deployment formats:
 ```
 
 Key OpenCode differences:
-- **Rules**: Loaded via `opencode.json` `instructions: ["rules/*.md"]` (no `@import`)
+- **Rules**: Core rules always loaded via `instructions`; on-demand rules via `@reference` in AGENTS.md (lazy loading, -62% tokens)
 - **Agents**: `mode: subagent`, no `name` field, tools as record format
 - **Commands**: `agent: build` + `model: provider/model-id` (model routing)
 - **Config**: `pactkit.yaml` in `.opencode/` (not `.claude/`)

{pactkit-2.0.2 → pactkit-2.1.1}/README.md

@@ -183,8 +183,8 @@ PactKit supports two deployment formats:
 
 ```
 ~/.config/opencode/
-├── AGENTS.md                 <- Slim header (rules loaded via instructions)
-├── rules/                    <- 7 rule modules (loaded via opencode.json instructions)
+├── AGENTS.md                 <- On-demand @reference index (lazy rule loading)
+├── rules/                    <- 8 rule modules (3 core always-load + 5 on-demand)
 ├── commands/                 <- 11 command playbooks (with model: routing)
 ├── agents/                   <- 9 agent definitions (mode: subagent)
 ├── skills/                   <- 10 skill packages (with SKILL.md frontmatter)
@@ -192,7 +192,7 @@ PactKit supports two deployment formats:
 ```
 
 Key OpenCode differences:
-- **Rules**: Loaded via `opencode.json` `instructions: ["rules/*.md"]` (no `@import`)
+- **Rules**: Core rules always loaded via `instructions`; on-demand rules via `@reference` in AGENTS.md (lazy loading, -62% tokens)
 - **Agents**: `mode: subagent`, no `name` field, tools as record format
 - **Commands**: `agent: build` + `model: provider/model-id` (model routing)
 - **Config**: `pactkit.yaml` in `.opencode/` (not `.claude/`)

{pactkit-2.0.2 → pactkit-2.1.1}/docs/architecture/governance/lessons.md

@@ -92,3 +92,10 @@
 | 2026-03-17 | When the target tool lacks `@import` syntax (OpenCode vs Claude Code), use its native config mechanism (`opencode.json` `instructions: ["rules/*.md"]`) for modular rule loading instead of inlining everything into a single file; `_update_global_opencode_json()` with merge strategy preserves user-owned fields (`provider`) while adding tool-managed fields (`instructions`) — same principle as `CLAUDE.local.md` but achieved through JSON merge instead of file separation | STORY-071 |
 | 2026-03-17 | Tool-internal config files (pactkit.yaml) must not be hardcoded to a single tool's directory — `load_config()` multi-path lookup (`.claude/` → `.opencode/`) with `find_pactkit_yaml()` helper + env-aware `resolve_pactkit_yaml_dir()` for generation keeps the CLI tool-agnostic; skill scripts (board.py) that run standalone cannot import library modules, so must inline the path lookup logic rather than calling `from pactkit.config import find_pactkit_yaml` | STORY-072 |
 | 2026-03-17 | OpenCode command-level model routing requires `model:` in frontmatter (not just `agent.{name}.model` in opencode.json) — `_resolve_opencode_model_id()` maps shortnames (sonnet/opus/haiku) to full `provider/model-id` by scanning `opencode.json` providers; `command_models` in pactkit.yaml enables user override; also: any config YAML comments referencing `~/.claude/` must be tool-agnostic since OpenCode users see those comments in `.opencode/pactkit.yaml` | STORY-073 |
+| 2026-03-17 | Tool integration checklists need a Dimension 0 capability matrix before any code — `docs/guides/tool-integration-checklist.md` shows that OpenCode (architecture-compatible with Claude Code) needed 6 stories while Codex (no agents, no rules, single provider) would require a completely different strategy; filling the matrix first prevents writing code that assumes the wrong architecture | STORY-slim-001 |
+| 2026-03-17 | When format-specific logic is scattered across 10+ locations (deployer, config, prompts), use a frozen dataclass registry (`FormatProfile` in `profiles.py`) so adding a new tool format requires only one registry entry — functions read `profile.skills_path_var`, `profile.excluded_agent_fields`, etc. instead of checking `if format == "opencode"`; review caught unreachable duplicate code from copy-paste during migration (lines 59-61 in `_rewrite_skills_prefix`) | STORY-slim-005 |
+| 2026-03-17 | Prompt templates with hardcoded env paths should use named placeholders (`{BOARD_CMD}`, `{SKILLS_ROOT}` etc.) resolved at deploy time by `_render_prompt(template, profile)`; use sequential `str.replace()` over `str.format_map()` because user-facing templates contain complex keys like `{R1, R2, ...}` and `{version}_*.mmd` that cause `ValueError: Empty attribute` in Python's format parser; f-string prompt constants must be converted to plain strings first | STORY-slim-006 |
+| 2026-03-17 | Document structure rules should live in a single `schemas.py` registry — `spec_linter.py` and `scaffold.py` both had diverged copies of required fields/patterns; when standalone skill scripts (board.py, scaffold.py) cannot import the library, inline copies with a `# STORY-slim-007: canonical values in src/pactkit/schemas.py` comment; standalone script fallbacks in spec_linter.py's except ImportError block must be kept bit-for-bit identical to schemas.py values | STORY-slim-007 |
+| 2026-03-17 | When two deploy functions share logic (classic/opencode), add missing functions one-by-one rather than creating a shared `_deploy_standard()` up-front — `_deploy_opencode()` was missing `auto_merge_config_file`, `_cleanup_legacy`, `_generate_project_agents_md`, and `_print_mcp_recommendations_opencode`; adding them separately is safer than a premature abstraction that could break the plugin/marketplace modes which use different parameter patterns (`_legacy_prefix`) | STORY-slim-008 |
+| 2026-03-18 | OpenCode `instructions: ["rules/*.md"]` glob loads ALL rules every turn (no lazy loading); the workaround is to split `RULES_FILES` into `RULES_CORE_FILES` (always-load via instructions, 3 files), `RULES_ONDEMAND_FILES` (referenced via `@rules/xxx.md` in AGENTS.md, AI reads on-demand via Read tool), and `RULES_INSTRUCTIONS_CORE` (list including user-managed files like `09-credential-safety.md`); user-managed files MUST NOT be in `RULES_FILES` (which drives `_deploy_rules`) or they cause `KeyError` in `prompts.RULES_MODULES` lookup | STORY-slim-009 |
+| 2026-03-17 | Architecture principles derived from project practice should be codified as a named rule module (08-architecture-principles.md) and deployed to all tool environments via `RULES_FILES`; the `CLAUDE_MD_TEMPLATE` auto-generate pattern (building `@import` list from `sorted(RULES_FILES.values())`) prevents new rules from being silently omitted from Classic mode while OpenCode picks them up via `instructions: ["rules/*.md"]` glob — a DRY fix exposed by adding the new module | chore/rules |

pactkit-2.1.1/docs/architecture/governance/rules.md

@@ -0,0 +1,25 @@
+# Governance Rules
+
+## Architecture Decisions
+
+| ID | Decision | Rationale | Date |
+|----|----------|-----------|------|
+| ADR-001 | Python 3.10+ with hatchling build | Broad compatibility, modern packaging | 2025-01 |
+| ADR-002 | Prompt templates as Python string constants | Zero external deps for core, easy to test | 2025-01 |
+| ADR-003 | pactkit.yaml for selective deployment config | User controls which agents/commands/rules deploy | 2025-02 |
+| ADR-004 | FormatProfile dataclass registry (`profiles.py`) | OCP: new tool = one registry entry; eliminates if-else branching | 2026-03 |
+| ADR-005 | schemas.py as document structure source of truth | DRY: one place for Spec/Board/Context/Lessons/TestCase rules | 2026-03 |
+| ADR-006 | Sequential str.replace in `_render_prompt()` | Safe with user-facing complex keys; format_map fails on `{R1, R2}` | 2026-03 |
+| ADR-007 | Deploy chain parity over premature abstraction | Add functions one-by-one rather than shared `_deploy_standard()` | 2026-03 |
+
+| ADR-008 | Lazy rule loading: RULES_CORE_FILES + RULES_ONDEMAND_FILES + RULES_INSTRUCTIONS_CORE | OpenCode instructions glob loads all files every turn; split avoids -62% token overhead | 2026-03 |
+
+## Invariants
+
+1. All 2325+ tests must pass before any commit to `main`.
+2. Specs (`docs/specs/`) are the source of truth — code conforms to specs, not the reverse.
+3. CLI entry point is `pactkit` via `src/pactkit/cli.py:main`.
+4. No runtime dependencies beyond `pyyaml`.
+5. New tool format requires only a `FormatProfile` entry — no other file changes needed.
+6. Document structure rules exist only in `schemas.py` — consumers inline with source-of-truth comment.
+7. `RULES_FILES` contains only PactKit-managed files; user-managed files (09-*, 10-*) go in `RULES_INSTRUCTIONS_CORE` only.

pactkit-2.1.1/docs/guides/codex-integration-preresearch.md

@@ -0,0 +1,185 @@
+# Codex CLI Integration Pre-Research
+
+> **Purpose**: Pre-research template for adapting PactKit to Codex CLI.
+> Fill in each "待填写" item before starting implementation.
+> Reference: `docs/guides/tool-integration-checklist.md` Dimension 1.
+>
+> **Codex CLI repo**: https://github.com/openai/codex
+> **Last updated**: 2026-03-17 (initial template)
+
+---
+
+## 0. Known Facts (from initial GitHub scan)
+
+| Fact | Source |
+|------|--------|
+| Has `.codex/skills/` directory | Repo root observed |
+| Uses `AGENTS.md` as project instruction file | Repo root observed |
+| Written in Rust | 96.2% Rust per GitHub |
+| Global config in `~/.codex/` | Logs written to `~/.codex/log/` |
+| Supports `codex exec` (non-interactive) | install.md |
+| OpenAI models only (ChatGPT Plus/Pro or API key) | README |
+
+---
+
+## 1. Target Tool Research
+
+### 1.1 Official Documentation URLs
+
+| Concept | URL | Status |
+|---------|-----|--------|
+| Agents (multi-role) | 待填写 | ❓ |
+| Commands (custom `/cmd`) | 待填写 | ❓ |
+| Skills format | 待填写 | ❓ |
+| Rules / AGENTS.md | 待填写 | ❓ |
+| Config format | 待填写 | ❓ |
+| Permissions / Sandbox | 待填写 | ❓ |
+| MCP support | 待填写 | ❓ |
+| Model selection | 待填写 | ❓ |
+
+### 1.2 Config Format Differences vs Claude Code
+
+| Feature | Claude Code | Codex CLI | Notes |
+|---------|-------------|-----------|-------|
+| Agent definition format | `.claude/agents/*.md` with YAML frontmatter | 待填写 | Does Codex have agents? |
+| Command format | `.claude/commands/*.md` with `allowed-tools:` | 待填写 | Unknown — Codex may not have custom commands |
+| Rules loading | `@import` in `CLAUDE.md` | 待填写 | `AGENTS.md` inline? |
+| Skill format | `SKILL.md` with `name`+`description` | 待填写 | `.codex/skills/` structure? |
+| Permission model | `settings.json` deny list | Sandbox mode (待填写 details) | What sandbox levels? |
+| Model config | N/A (Anthropic only) | 待填写 | How to select GPT-4o vs o3? |
+
+### 1.3 File System Conventions
+
+| Path | Purpose | Status |
+|------|---------|--------|
+| `~/.codex/` | Global config dir | Confirmed (log dir exists) |
+| `~/.codex/config.toml`? | Global config file | 待填写 — confirm filename and format |
+| `.codex/` | Project config dir | Confirmed (skills dir exists) |
+| `.codex/skills/` | Project skills | Confirmed |
+| `./AGENTS.md` | Project instruction file | Confirmed (repo has it) |
+| `.codex/pactkit.yaml`? | PactKit config location | 待填写 — confirm `.codex/` is right choice |
+
+### 1.4 Rules Loading Mechanism
+
+| Question | Answer |
+|----------|--------|
+| Does Codex support `@import` or similar? | 待填写 |
+| How does Codex load `AGENTS.md`? | 待填写 |
+| Can multiple rule files be referenced? | 待填写 |
+| Is there an `instructions` field or equivalent? | 待填写 |
+| What is the context window limit? | 待填写 |
+
+### 1.5 Model Routing
+
+| Question | Answer |
+|----------|--------|
+| Can different agents use different models? | 待填写 |
+| Can different commands use different models? | 待填写 |
+| How is model specified (config file, CLI flag)? | 待填写 |
+| What models are available? | 待填写 (GPT-4o, o3, o4-mini?) |
+| Is there a `small_model` equivalent? | 待填写 |
+
+### 1.6 Permission / Sandbox Model
+
+| Question | Answer |
+|----------|--------|
+| What sandbox levels exist? | 待填写 |
+| How is file write permission controlled? | 待填写 |
+| How is shell command permission controlled? | 待填写 |
+| Is there a deny list format? | 待填写 |
+| How does it compare to Claude Code `settings.json`? | 待填写 |
+
+### 1.7 MCP Support
+
+| Question | Answer |
+|----------|--------|
+| Does Codex support MCP? | 待填写 |
+| MCP server format (if supported)? | 待填写 |
+| Any pre-built MCP integrations? | 待填写 |
+
+### 1.8 Image / Vision Support
+
+| Question | Answer |
+|----------|--------|
+| Does Codex support image input? | 待填写 |
+| How to paste/reference images? | 待填写 |
+| Vision capability declaration needed? | 待填写 |
+
+### 1.9 `settings.json` Equivalents
+
+| Claude Code `settings.json` Feature | Codex Equivalent | Notes |
+|-------------------------------------|------------------|-------|
+| `permissions.deny` | 待填写 | |
+| `mcpServers` | 待填写 | |
+| `defaultMode: bypassPermissions` | 待填写 | |
+| `env` variables | 待填写 | |
+| `hooks` | 待填写 | |
+
+### 1.10 Dual-Layer Architecture
+
+| Question | Answer |
+|----------|--------|
+| Does Codex distinguish global (`~/.codex/`) from project (`.codex/`)? | 待填写 |
+| What goes in global vs project? | 待填写 |
+| Does `pactkit init --format codex` write to global? | 待填写 |
+| Does `/project-init` write to project? | 待填写 |
+
+---
+
+## 2. Capability Matrix (fill in after research)
+
+Based on 1.1–1.10 answers, fill in the `Codex` column in the checklist:
+
+```
+docs/guides/tool-integration-checklist.md → Dimension 0.1
+```
+
+Then determine strategy from Dimension 0.2.
+
+---
+
+## 3. Preliminary Integration Strategy (hypothesis)
+
+Based on known facts (update after full research):
+
+| Capability | Hypothesis | Confidence |
+|------------|-----------|------------|
+| Agents | None → embed roles in AGENTS.md | Medium |
+| Commands | Exists but different format → convert | Low |
+| Skills | `.codex/skills/` → adapt discovery | Medium |
+| Rules | No `@import` → inline into AGENTS.md | Medium |
+| Model routing | None → prompt-level Model Guard Protocol | Medium |
+| Provider | OpenAI only → no resolver needed | High |
+| Permission | Sandbox mode → different from deny list | Low |
+| pactkit.yaml location | `.codex/pactkit.yaml` | Medium |
+
+---
+
+## 4. Open Questions (to resolve before coding)
+
+1. Does Codex have a concept of custom agents (multi-role)? Or is it always single-agent?
+2. What is the exact format for custom commands in Codex?
+3. What does `.codex/skills/` expect — same `SKILL.md` frontmatter as OpenCode?
+4. Is there a global config file (`~/.codex/config.toml`?) and what fields does it support?
+5. How does Codex handle `AGENTS.md` — is it a system prompt? Loaded on startup?
+6. Is the sandbox mode configurable or fixed?
+7. Does Codex have an equivalent to `opencode.json` `instructions` field?
+8. What version of Codex should we target? (CLI is Rust-based, separate from Codex Web)
+9. **Version compatibility**: Should PactKit check `codex --version` at deploy time and warn if below minimum? What is the minimum version that supports skills/AGENTS.md?
+
+---
+
+## 5. Estimated Effort (fill in after research)
+
+| Dimension | Estimated Stories | Notes |
+|-----------|------------------|-------|
+| 2: Deploy architecture | 待填写 | |
+| 3: Agent format | 待填写 | Likely: N/A if no agent concept |
+| 4: Command format | 待填写 | |
+| 5: Rules loading | 待填写 | Likely: inline into AGENTS.md |
+| 6: Skills format | 待填写 | |
+| 7: pactkit.yaml | 待填写 | Add `.codex/` to candidates |
+| 8: Playbook text | 待填写 | |
+| 9: CLI | 待填写 | Add `codex` to format choices |
+| 10: Verification | 待填写 | |
+| **Total** | | |