Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

935 Commits

Folders and files

Repository files navigation

project-init — Adaptive AI Development Organization Framework

人間とAIエージェントが参加するソフトウェア開発について、要求を保存したシステム全体の改善と、その保証・受理を支える開発環境をproject-localに初期化・維持するframeworkです。組織の不変条件とOperating Model / Practiceに加え、コード・Skill・設定・検査を一体で扱います。

特定のagent、provider、IDE、planning tool、worktree manager、branch topologyを「正しさ」そのものとして固定しません。最上位のConstitutionを満たす範囲で、現在の標準workflowを使いながら、より良いmechanismへのrefinement / deviationを許容します。

Organization architecture

  • constitution/CONSTITUTION.md — tool/provider-independentなorganizational kernel
  • organization/ — Operating Modelとcurrent profile
  • formal/ — Constitutionのabstract state-transition model
  • skills/ — context-dependent judgment / playbook
  • catalog/ — 能力の一覧と、外部を含むSkill候補の評価記録。導入するSkillの選定に使う(skill-selection)
  • docs/adr/ — long-lived decision history

現在の標準は release-driven solo development profile です。GitHub / Linear / release branch / Worktrunk / mise等の既存workflowはここで維持されます。

Usage

Initialization prompt

新規または既存 project で通常の /init 相当処理と同時に PROMPT.ja.md を渡してください。prompt は初期化手順と profile / Skill へのroutingだけを持ち、詳細ruleの正本は profile / Skill です。

初期化時だけ prompt で repository を調査し、日常運用では短い root contract + project-local Agent Skills へ progressive disclosure することを目的とします。

Install Agent Skills with bunx skills / npx skills

skills/ 配下の Agent Skills は skills CLI から直接導入できます。

Bun を利用している場合は bunx skills を推奨します。Node.js / npm 環境では同じ引数を npx skills で実行できます。

利用可能な Skill を確認:

bunx skills add rebuildup/project-init --list
# or
npx skills add rebuildup/project-init --list

対話的に選択して current project へ導入:

bunx skills add rebuildup/project-init
# or
npx skills add rebuildup/project-init

特定のSkillと、その必須依存を導入:

bunx skills add rebuildup/project-init --skill quality-gate system-quality
# or
npx skills add rebuildup/project-init --skill quality-gate system-quality

metadata.requires-skills に依存があるSkillは、その依存も同時に導入します。設計・判断・品質・評価・選定Skillの共有契約はsystem-qualityです。単独copyだけでは導入完了になりません。

Codex を明示して導入:

bunx skills add rebuildup/project-init --agent codex
# or
npx skills add rebuildup/project-init --agent codex

全 Skill を Codex に導入:

bunx skills add rebuildup/project-init --skill '*' --agent codex
# or
npx skills add rebuildup/project-init --skill '*' --agent codex

-g / --global を付けると project-local ではなく user scope に導入できます。

既にSkillが導入済みでも、それだけで「更新不要」と判断しません。明示的にversionをpin/freezeしていない限り、配布元のcurrent revision/contentとの差分を確認し、変更があればproject-local customizationを保持しながらreconcile/updateします。配布元やrevisionを確認できない場合も、agentが独断で据え置き扱いにはしません。

Important

bunx skills add / npx skills add が導入するのは skills/ 配下の Agent Skills です。ルートの PROMPT.ja.md は初期化用の prompt であり、Skills CLI によって自動実行・適用されるものではありません。

新規 project の初期構築には PROMPT.ja.md を使用し、その後の日常運用で必要な Skill を bunx skills または npx skills から導入する、という役割分担を想定しています。

Adaptive test scheduling

開発中の任意・反復テストを変更状態と成功履歴から選択的に実行するPracticeは quality-gate で定義します。フレームワーク非依存の参照実装、設定例、適用条件は templates/quality を参照してください。必須のCI・統合・リリース検証は省略しません。

システム品質の検証

system-quality は要求保存・全体構成の比較・既知アンチケース排除を結び付けます。ShellCheckが利用できる環境で、bun run quality:structure は自前fileの分類、設定構文、ShellCheck、TypeScript適用範囲・抑制、Markdown参照を検査します。bun run quality:challenge は実repoのコピーへ違反と正当変更を混入して検査の応答を確認します。bun run test:system-quality はexecutorと改善比較の回帰を実行します。

Trusted quality contract workflowは信頼済みrevisionと候補SHAの契約変更を比較します。受理側でそのrevisionとstatusを強制する設定は別途必要です。これらの検査は意味上の完全性や最適性の証明ではありません。

Delivery model

標準deliveryはGitHub IssuesとPull Requestsを中心とし、1週間のplanning checkpointと適応的なrelease batching を組み合わせます。週次終了は自動リリースのtriggerではありません。release planning / health / portfolio control plane は Linear に統一し、GitHub Projects は標準運用へ導入しません。GitHub Issues は implementation / dependency の durable SoT として維持します。

  • main = released/integrated source state
  • release-x-y-z = target version integration branch(開発中は常時release-readyでなく、ticketを自律統合して集約。重いCI/実機受入は原則candidate freeze後)
  • version bumpはrelease intent・互換性・公開する変更の意味から決定する(通常のmajor/minor/patchを参考とし、sprint境界だけではbumpしない)
  • release train = target version + release branch。複数週次checkpointへの持ち越しや早期リリースを許容し、変更量・公開価値・滞留・release-onlyコストで候補化を判断する
  • 1 top-level Issue = 1 number-only ticket branch = 1 ticket PR
  • Issue dependency graph = canonical dependency SoT
  • independent ticket PRはtarget release branchへ向ける
  • same-releaseのlinear hard dependencyはstacked PRとしてpredecessor branchへ向けられる
  • durable branchはfirst meaningful commit直後にPRを必ず作成し、active/incompleteならDraft、readiness条件を満たしていればReady for reviewにする。作成時点で完成済みなら最初からReadyとし、worker/subagentも例外にしない
  • PR作成時にIssue linkage、assignee、reviewer/CODEOWNERS、repository-established labels、target release、stack contextを適切に設定する
  • stack predecessor変更後はcurrent SHAでaffected validationを再実行する
  • non-release ticket PRはreadiness/quality gate通過後に追加のmerge許可を待たず自律landingする
  • target release trunk landing後はIssueを明示closeし、dependent PRをreconcileしたうえでsafeならticket branchを削除する
  • PRなしticket branch / Ready未landing PR / land済みopen Issue / merged後残存branchをrecovery/completion時にrepairする
  • release branchに最初のmeaningful integrated differenceが入った直後にDraft release PRを開き、release PRだけはexplicit user authorizationなしにmergeしない

詳細は skills/github-delivery/SKILL.md、ADR-0032、ADR-0008、CONTRIBUTING.md を参照してください。

Repository layout

.
├─ PROMPT.ja.md
├─ README.md
├─ CONTRIBUTING.md
├─ LICENSE
├─ catalog/
│  ├─ capabilities.tsv
│  └─ candidates.tsv
├─ constitution/
│  └─ CONSTITUTION.md
├─ organization/
│  ├─ README.md
│  ├─ execution-roles.md
│  └─ profiles/
│     └─ release-driven-solo.md
├─ formal/
│  ├─ Organization.tla
│  ├─ Organization.cfg
│  └─ README.md
├─ docs/
│  ├─ policy-overview.md
│  ├─ policy-integrity.md
│  ├─ adr/
│  │  └─ ADR-0001.md ... ADR-0037.md
│  └─ roles/
│     ├─ CODEX_ROLES.ja.md
│     └─ CODEX_ROLES.en.md
└─ skills/
   ├─ agent-delivery-estimation/
   ├─ agent-recovery/
   ├─ code-naming/
   ├─ correctness-assurance/
   ├─ design-refinement/
   ├─ engineering-decisions/
   ├─ github-delivery/
   ├─ idea-discovery/
   ├─ herdr-runtime/
   ├─ interaction-discipline/
   ├─ linear-release-control/
   ├─ onboarding/
   ├─ orca-frontend/
   ├─ parallel-orchestration/
   ├─ policy-evaluation/
   ├─ quality-gate/
   ├─ sandbox-runtime/
   ├─ secrets-management/
   ├─ security-audit/
   ├─ security-maintenance/
   ├─ system-quality/
   ├─ skill-selection/
   └─ worktree-workflow/

Documentation

  • docs/policy-overview.md — policy 全体の背景、実行モデル、GitHub delivery、quality/security/recovery 方針。

  • docs/adr/ — 長期的な architecture / workflow / quality / recovery decisions。

  • ADR-0009 — GitHub Actions の cost-aware CI resource efficiency policy。

  • ADR-0010 — AI agent delivery の evidence-based forecasting / capacity estimation policy。

  • ADR-0011 — Agent policy を eval 可能な executable contract として扱う policy evaluation model。

  • ADR-0012 — release PR mergeのexplicit human-authorization boundary。ticket PRへの一律適用はADR-0027でsuperseded。

  • ADR-0027 — autonomous ticket landing、Issue close、branch cleanup、guarded release merge boundary。

  • ADR-0028 — 初期化promptをroutingに縮約し、英語版を廃止。

  • ADR-0029 — 能力の一覧と候補記録による、再現可能なSkill選定。

  • ADR-0030 — writing-disciplineをwriting-skillsへ一本化し、導入した複製をhashで検査する。

  • ADR-0031 — worktree lifecycleをfrontendから独立させ、Orcaを任意のfrontendとして併用する。

  • ADR-0013 — WSL/Linux の worktree 運用を Worktrunk へ集約する default layer 採用。

  • ADR-0014 — GitHub execution state を canonical としたまま Linear を optional release control plane として導入する境界。

  • ADR-0015 — advisory maintenance と active source audit を分離し、coverage-led security auditを標準化する判断。

  • ADR-0016 — current release-driven profileのLinear / version / main protection / Worktrunk defaults。

  • ADR-0017 — Constitution / Operating Model / Practice / Skillを分離し、refinement・policy decay・formal modelを導入するorganizational architecture。

  • ADR-0018 — current release-driven profileのPR landingをmerge commitへ固定し、squash/rebase mergeを無効化する判断。

  • ADR-0022 — miseをproject-local toolchain/bootstrapの標準Practiceとして採用し、native version source・Nix/containerとの責務境界を定義する判断。

  • ADR-0023 — application secret valueをInfisicalへ集約し、current default control planeをself-hosted https://secrets.rebuildup.dev としたうえで、repository-controlled schema / CLI-first / OIDC / least-privilegeを標準化するPractice。

  • ADR-0024 — Rust/Cargo worktreeのmutable build outputを隔離しつつ、reflink seed・sccache・selective cleanup・profile tuningで容量とcold-startを最適化するPractice。

  • ADR-0025 — adaptive fan-out / fan-in、native subagentとtop-level Workerのrouting、Herdrによるagent-driven Supervisor loopを定義する方針。

  • ADR-0026 — Cloudflare利用projectで cf をprimary CLI、Wranglerを明示的compatibility fallbackとするPractice。

  • ADR-0019 — Worker / Supervisorをlogical roleとして定義し、execution attemptをobservational / mutable / durableへ段階化する判断。

  • ADR-0035 — dedicated non-authoring SupervisorとWorkerの実権限分離、hookとOS/remote Broker境界の区別。

  • docs/roles/ — 時点依存の Codex logical role policy。

  • CONTRIBUTING.md — policy 更新時の整合性・review rules。

  • ADR-0037 — 要求保存・全体改善と実成果物の品質制約。

Agent Skills

通常 task では必要な Skill だけを読み込みます。ただし、README / documentation / ADR / Issue / Pull Request / commit message / code comment / review comment / release note等のpersistent reader-facing proseを作成・更新する場合、writing-discipline はpre-writeの必須routingとして扱います。

  • parallel-orchestration — Worker / Supervisor role、attempt-class routing、subagent 分解・snapshot/result・stack-ready dependency 統合
  • sandbox-runtime — isolated runtime と cross-platform portability
  • github-delivery — Issues / weekly planning + adaptive release batching / stacked PR / PR state lifecycle。release planning / health / portfolio control planeはLinearに統一
  • herdr-runtime — Herdrをoptional Supervisor/session Practiceとして使う時のagent lifecycle mapping / agent-driven fan-out / recovery boundary
  • supervisor-boundary — dedicated Supervisorの直接実装を防ぐ権限契約。templates/supervisor-boundary/ にClaude Code用deny-by-default参考hookを用意(OS/credential/Broker境界の実機検証は別途必須)
  • templates/agent-routing/ — role別のtop-level委譲先をHerdr + dotfilesの統一agent launcherへ固定する参照CLI。run/evalは環境別に検証が必要
  • agent-delivery-estimation — Work Unit / dependency / observed throughput / human・CI・usage constraints による中長期delivery forecast
  • system-quality — 要求保存、全体再構成、既知アンチケース排除、改善関係と保証の分離。実成果物challengeを同梱
  • quality-gate — stack-aware quality profile、current-SHA revalidation、verification taxonomy、GitHub Actions resource efficiency
  • engineering-decisions — project 内の判断優先順位と escalation policy
  • security-audit — source codeの未知脆弱性をcoverage-ledに探索し、fresh verifierで反証してstructured findingへ確定
  • security-maintenance — framework/runtime 脆弱性の intake / triage / remediation と confirmed finding のproject priority化
  • onboarding — fresh contributor 向け documentation 設計
  • agent-recovery — session/sandbox/context 中断からの durable recovery
  • correctness-assurance — 正しい答えを作る前提 / 不変条件・事前/事後条件の抽出 / 型・静的解析・runtime assertion・テスト・property/differential testing・formal verification・reviewからの最小十分な保証手段設計
  • code-naming — シンボル・ファイル・ディレクトリの命名を参照箇所、意味の区別、冗長性、規約、互換性から判断
  • policy-evaluation — execution profile / cold review / deterministic vs latent eval / context-budget model / policy regression guard
  • design-refinement — 実装前 evidence-first design / unknown 分解 / scope-risk 調整 / trade-off documentation
  • writing-discipline — reader-oriented writing。正本は rebuildup/writing-skills で、このrepositoryは .claude/skills/ にlock付きで導入している
  • interaction-discipline — agent ownership / blocker presentation / one-question escalation / tangent defer / persistent prose routing
  • linear-release-control — Linear を標準 release planning / health / portfolio control plane として使う契約
  • worktree-workflow — Worktrunk を WSL/Linux の標準 worktree 操作 layer として使う契約 / branch base / port allocation / Rust-Cargo build cache lifecycle
  • idea-discovery — 既存の延長ではない発想を求められた時に、候補の順位づけではなく一つの考えを使って生まれる問いと成果で進め、後付けの正当化と区別する(仮説段階)
  • orca-frontend — Orcaを任意のworktree / agent terminal frontendとして併用し、lifecycle・作業の正本・orchestration stateをOrcaに依存させない
  • skill-selection — 能力ごとに担当Skillを1つ決め、外部Skillを個別に導入して skills-lock.json と採否を記録する

Core principle

Constitutionはtool/provider-independentなorganizational propertyだけを定義する。現在のGitHub / Linear / release branch / Worktrunk / mise / Skill等は、それらを満たすOperating Model / Practiceであり、同等以上のguaranteeを示せるより良い手段へ置換できる。agentはprocedure compliance自体ではなく、Constitutionとexplicit decisionの制約下でproject全体を最適化する。

About

No description, website, or topics provided.

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages