@dobbymin/github-convention-skill 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +21 -4
- package/skill/SKILL.md +108 -0
- package/skill/references/git-pr.md +41 -0
- package/skill/references/issue-planning.md +48 -0
- package/skill/references/orchestration.md +71 -0
- package/skill/references/security-release.md +25 -0
- package/skill/references/state-recovery.md +35 -0
- package/README.md +0 -3
package/package.json
CHANGED
|
@@ -1,6 +1,23 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dobbymin/github-convention-skill",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"engines": {
|
|
6
|
+
"node": ">=22"
|
|
7
|
+
},
|
|
8
|
+
"repository": "https://github.com/Dobbymin/github-convention",
|
|
9
|
+
"homepage": "https://github.com/Dobbymin/github-convention#readme",
|
|
10
|
+
"exports": {
|
|
11
|
+
"./package.json": "./package.json"
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"package.json",
|
|
15
|
+
"skill"
|
|
16
|
+
],
|
|
17
|
+
"githubConvention": {
|
|
18
|
+
"compatibleCli": "^0.1.0"
|
|
19
|
+
},
|
|
20
|
+
"publishConfig": {
|
|
21
|
+
"access": "public"
|
|
22
|
+
}
|
|
23
|
+
}
|
package/skill/SKILL.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: github-convention
|
|
3
|
+
description: Apply a consistent, safe, Issue-driven GitHub development workflow. Use when analysing a repository, planning or splitting work into Issues, coordinating optional parallel agents, implementing a task, creating or updating a PR, handling review/CI feedback, recovering interrupted work, or preparing a release. Do not invoke for unrelated coding questions that do not involve the repository's GitHub workflow.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GitHub Convention
|
|
7
|
+
|
|
8
|
+
You are the Main Agent / Orchestrator unless the user explicitly assigns you a worker task. Keep the workflow Issue-centric, preserve existing project conventions, and never infer approval.
|
|
9
|
+
|
|
10
|
+
## First-run and resume protocol
|
|
11
|
+
|
|
12
|
+
1. Identify the repository root and default branch. Do not assume the default branch is `main` until verified.
|
|
13
|
+
2. If the `github-convention` CLI is installed, use `github-convention doctor`, `validate`, and `status` as appropriate. Use `--output json` for machine parsing and `--dry-run` before mutations.
|
|
14
|
+
3. Read Project Config at `.github-convention/config.yaml`, convention documents under `.github-convention/conventions/`, and the cached project analysis if present.
|
|
15
|
+
4. Compare analysis source hashes. Re-analyse changed or new project instruction files only; do not trust cache over current files.
|
|
16
|
+
5. Read the active Local State for this execution. Query GitHub live for all Issues, dependencies, PRs, branches, and CI states that affect the next action.
|
|
17
|
+
6. GitHub is authoritative for remote work state. Local State is authoritative only for local execution detail. If approval cannot be verified, ask again. If worktree ownership or diff is unclear, stop and report.
|
|
18
|
+
7. Do not ask the user to repeat a decision already recorded in this Skill, Project Config, or active State.
|
|
19
|
+
|
|
20
|
+
## Planning workflow
|
|
21
|
+
|
|
22
|
+
1. Inspect existing project instructions, templates, commit/branch patterns, scripts, quality gates, labels, CI, and release policy.
|
|
23
|
+
2. If project documents conflict with Project Config or each other, show the conflicting sources and ask the user. Record the resolution so it is not repeatedly asked.
|
|
24
|
+
3. Decompose work into independently implementable and verifiable tasks. Do not split work merely to increase parallelism.
|
|
25
|
+
4. Create a dependency DAG. Use a hard `Blocked by` dependency only when a downstream task truly cannot proceed before the upstream task completes.
|
|
26
|
+
5. FE/BE work may run in parallel when an API/interface contract is settled and documented. If the contract is uncertain, resolve it first or make the implementation a true dependency.
|
|
27
|
+
6. Present draft Parent Issues grouped by Parent. Allow group-level approval and per-Issue edit/approve/reject/exclude.
|
|
28
|
+
7. Create only approved Issues. Keep unapproved drafts in Local State. Before each remote write, query GitHub and check for duplicates.
|
|
29
|
+
8. If an approved Issue depends on an excluded/unapproved Issue, keep it approved but mark it blocked; do not silently remove the dependency.
|
|
30
|
+
|
|
31
|
+
## GitHub artifact language
|
|
32
|
+
|
|
33
|
+
- Write Issue titles and bodies, PR titles and bodies, and commit subjects and bodies in Korean when the user writes in Korean or asks for Korean. Use the user's language otherwise. Repository templates and English examples never override this rule.
|
|
34
|
+
- Keep technical identifiers, commands, code, API names, required GitHub closing keywords, and Conventional Commit type prefixes unchanged. Write the human-readable text after the prefix in Korean (for example, `feat: 로그인 세션 갱신 처리`).
|
|
35
|
+
- Before any GitHub write or commit, check that the title and body/subject follow the selected language. Fix drafts that do not.
|
|
36
|
+
|
|
37
|
+
## Execution policy
|
|
38
|
+
|
|
39
|
+
1. Choose the simplest safe mode: Main Agent alone, sequential execution, or optional parallel workers.
|
|
40
|
+
2. Use Sub Agents only when tasks are sufficiently independent and the runtime supports useful delegation. Otherwise work sequentially.
|
|
41
|
+
3. Set concurrency from the user/project cap, runtime capacity, resource budget, dependency graph, and file-overlap risk. Never assume unlimited workers.
|
|
42
|
+
4. Give each worker a single Issue, acceptance criteria, interface context, allowed scope, file ownership hints, and test commands.
|
|
43
|
+
5. Isolate workers in verified native workspaces when possible; otherwise use Git Worktree. One worker per writable workspace.
|
|
44
|
+
6. Workers may implement and test only. They must not commit, push, create/edit/close Issues, create PRs, merge, resolve review threads, or write shared Local State.
|
|
45
|
+
7. Require the English Task Report format in `references/orchestration.md`.
|
|
46
|
+
8. Inspect every worker's actual diff and rerun relevant tests. Do not trust a report without verification.
|
|
47
|
+
9. Commit each independently scoped work unit after its acceptance criteria, relevant checks, and secret scan pass. The Orchestrator commits; workers never do. Do not start unrelated work with a completed unit left uncommitted.
|
|
48
|
+
10. Independent tasks continue if another worker fails. Stop only that task and its hard dependents. Retry up to two times after the initial attempt unless the error is clearly non-retryable.
|
|
49
|
+
11. After retry exhaustion, prepare a new follow-up Issue under the existing Parent. Preserve partial work and failure context. Obtain user approval before creating it.
|
|
50
|
+
|
|
51
|
+
## Git and PR authority
|
|
52
|
+
|
|
53
|
+
- You, the Orchestrator, own all Git and GitHub mutations, including branches, worktrees, rebase, commit, push, Issue/Label/dependency changes, PR creation, and review-thread resolution.
|
|
54
|
+
- Prefer the user's existing `gh auth` session. Use an already-connected Agent GitHub tool only when `gh` cannot perform the needed operation.
|
|
55
|
+
- Never push directly to the protected default branch. Never merge a PR; the user owns Merge.
|
|
56
|
+
- Each Sub-issue has its own branch and PR. Do not create Draft PRs by default.
|
|
57
|
+
- Before PR creation, fetch/rebase latest default branch, rerun impacted checks, perform self-review, run secret scan, and ensure acceptance criteria pass.
|
|
58
|
+
- Project PR title conventions win. Otherwise use Conventional Commit style and include the Issue number.
|
|
59
|
+
- Never use plain `git push --force`; use `--force-with-lease` only when required on a branch you own and after verifying remote state.
|
|
60
|
+
|
|
61
|
+
## Approval boundaries
|
|
62
|
+
|
|
63
|
+
Always obtain explicit user approval before:
|
|
64
|
+
|
|
65
|
+
- Creating new GitHub Issues from generated drafts.
|
|
66
|
+
- Installing new project tools or changing hook/CI configuration.
|
|
67
|
+
- Applying Branch Protection/Ruleset changes.
|
|
68
|
+
- Making architecture, business-logic, or requirements changes requested in review.
|
|
69
|
+
- Rolling back a deployment.
|
|
70
|
+
- Creating Git Tags or GitHub Releases.
|
|
71
|
+
- Performing a destructive operation when ownership or data safety is unclear.
|
|
72
|
+
|
|
73
|
+
Never treat `--yes`, non-interactive mode, a previous ambiguous response, or silence as approval for these actions. In non-interactive mode return an approval-pending result and stop the protected operation.
|
|
74
|
+
|
|
75
|
+
## Quality and security
|
|
76
|
+
|
|
77
|
+
- Reuse existing format/lint/type/test/hook/secret-scanning tools before proposing new ones.
|
|
78
|
+
- New code-caused Lint, Type, Test, or Build failures must be fixed; do not bypass them as environment problems.
|
|
79
|
+
- Hook bypass is allowed only for a diagnosed tool/environment problem. Record the exact command and reason. Never delete or permanently disable hooks.
|
|
80
|
+
- Secret scanning is required. Reuse the existing scanner; if none exists, propose one and obtain approval before installation.
|
|
81
|
+
- A likely real secret blocks commit/push. Redact the value from reports/logs. If already exposed remotely, advise revoke/rotate; deleting the line alone is insufficient.
|
|
82
|
+
- Do not overwrite user changes, untracked work, or files outside the assigned task scope.
|
|
83
|
+
|
|
84
|
+
## PR review and CI response
|
|
85
|
+
|
|
86
|
+
- Handle simple naming/style/exception/test requests automatically.
|
|
87
|
+
- Ask before architecture, business-logic, or requirement changes.
|
|
88
|
+
- Re-run tests and self-review after every fix. Orchestrator commits and pushes to the existing PR branch.
|
|
89
|
+
- Auto-resolve only simple review threads fully addressed and verified; leave design/discussion threads open.
|
|
90
|
+
- Classify CI failures. Code-caused failures get up to two retries; transient external/network errors up to three. Permissions, secrets, and user-owned configuration require user input.
|
|
91
|
+
- After exhaustion, propose a follow-up Issue under the Parent (approval required).
|
|
92
|
+
|
|
93
|
+
## Deployment and release
|
|
94
|
+
|
|
95
|
+
- After Merge, verify the PR and Issue state and inspect configured deployment/Health Check results.
|
|
96
|
+
- Retry transient errors within bounds. If Health Check fails, stop further deployment actions and report.
|
|
97
|
+
- Never auto-rollback; request approval.
|
|
98
|
+
- Respect existing release policy. If none exists, use Semantic Versioning, draft CHANGELOG/Release Notes, and ask approval before Tag/Release creation.
|
|
99
|
+
|
|
100
|
+
## Required references
|
|
101
|
+
|
|
102
|
+
Load only the focused reference needed for the current step:
|
|
103
|
+
|
|
104
|
+
- `references/issue-planning.md` — Parent/Sub-issue, approvals, dependencies, templates.
|
|
105
|
+
- `references/orchestration.md` — worker contract, dynamic concurrency, isolation, retries.
|
|
106
|
+
- `references/git-pr.md` — branch/rebase/commit/PR/review/CI rules.
|
|
107
|
+
- `references/state-recovery.md` — Local State, locking, resume, archive.
|
|
108
|
+
- `references/security-release.md` — secrets, hooks, deployment, release, notifications.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Git and Pull Request Reference
|
|
2
|
+
|
|
3
|
+
## Artifact language
|
|
4
|
+
|
|
5
|
+
Write commit messages (subjects and bodies) and PR titles/bodies in the user's language. For Korean-language work, use Korean for the human-readable text; keep Conventional Commit type prefixes (such as `feat:`), Issue numbers, and required closing keywords such as `Closes #123` unchanged.
|
|
6
|
+
|
|
7
|
+
## PR template precedence
|
|
8
|
+
|
|
9
|
+
Use the target repository's existing PR body template, including `.github/pull_request_template.md`, when present. `templates/PULL_REQUEST_TEMPLATE.md` is a reusable default only when the target has no suitable template. Keep the matching Issue close keyword in the PR body; for a Sub-issue PR, close the child Issue rather than its Parent.
|
|
10
|
+
|
|
11
|
+
## Git ownership
|
|
12
|
+
|
|
13
|
+
Orchestrator owns all branch, worktree, rebase, commit, push, PR, and Issue mutations. Workers do not perform Git/GitHub write operations. User owns PR Merge.
|
|
14
|
+
|
|
15
|
+
## Work-unit commits
|
|
16
|
+
|
|
17
|
+
Commit each independently scoped work unit after its acceptance criteria and relevant checks pass. Do not leave a completed work unit uncommitted while starting unrelated work. If workers implement separate parts, the Orchestrator verifies and commits each completed unit; workers never commit. A larger Issue may therefore produce multiple commits on its branch.
|
|
18
|
+
|
|
19
|
+
## Before creating a PR
|
|
20
|
+
|
|
21
|
+
1. Verify acceptance criteria.
|
|
22
|
+
2. Run repository quality checks and tests.
|
|
23
|
+
3. Run secret scan.
|
|
24
|
+
4. Inspect the complete diff and perform self-review.
|
|
25
|
+
5. Fetch and rebase latest configured default branch.
|
|
26
|
+
6. Re-run tests affected by the rebase.
|
|
27
|
+
7. Verify Issue title/body/labels/links.
|
|
28
|
+
|
|
29
|
+
Do not create Draft PRs by default. Each Sub-issue gets its own PR. Use repository naming conventions first; otherwise propose a conventional branch/commit/title scheme. PR title fallback includes the Issue number.
|
|
30
|
+
|
|
31
|
+
## Updating other open PRs
|
|
32
|
+
|
|
33
|
+
After a PR merges, inspect the changed files and dependency graph. Rebase only branches materially affected by the change. Coordinate with or pause an active worker before changing its workspace. Resolve simple conflicts only; ask on complex conflicts or design decisions.
|
|
34
|
+
|
|
35
|
+
## Review requests
|
|
36
|
+
|
|
37
|
+
Auto-fix straightforward style, naming, exception handling, or missing test requests. Ask before architecture, business-logic, or requirement changes. Re-run checks and self-review; update the same PR. Resolve only simple verified threads; keep design discussions open.
|
|
38
|
+
|
|
39
|
+
## CI failures
|
|
40
|
+
|
|
41
|
+
Classify code/test/lint/type/build problems (up to two retries), transient network/external service problems (up to three retries), and user-controlled permission/secret/configuration issues (ask user). After retry exhaustion, propose a follow-up Issue under the Parent.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Issue Planning Reference
|
|
2
|
+
|
|
3
|
+
## Parent and Sub-issue structure
|
|
4
|
+
|
|
5
|
+
- Create one Parent Issue for a cohesive outcome, then create a Sub-issue for each independently implementable task. Use a standalone Issue only when no parent outcome groups the work.
|
|
6
|
+
- A markdown checklist or a draft display grouped by Parent is not a GitHub parent-child relationship. After the approved Issues exist, create the native Sub-issue relationship using GitHub's REST API (`POST /repos/{owner}/{repo}/issues/{parent_number}/sub_issues` with the child Issue ID), or set `parent_issue_id` when creating the child. Verify each relationship by reading the child’s parent Issue.
|
|
7
|
+
- Use GitHub native `Blocked by`/`Blocking` relationships only for hard execution dependencies. Parent-child grouping alone does not imply a blocker.
|
|
8
|
+
- Keep the Parent Issue's checklist synchronized for readability, but treat the native relationship as authoritative.
|
|
9
|
+
|
|
10
|
+
## Template precedence and native links
|
|
11
|
+
|
|
12
|
+
- Prefer the target repository's existing Issue templates. GitHub UI Markdown templates commonly live in `.github/ISSUE_TEMPLATE/`; `config.yml` can disable blank Issues. A PR body template commonly lives at `.github/pull_request_template.md`.
|
|
13
|
+
- Reuse bundled templates only when the target repository has no suitable template. Do not overwrite or copy repository-specific `.github` templates automatically.
|
|
14
|
+
- Parent numbers and body checklists are descriptive only. For Issues created by the Orchestrator, create the approved Issue first, add the child through GitHub's native Sub-issue API, and verify its parent. For Issues created manually in GitHub UI, use the native relationship control; do not add an Action that infers relationships from body text.
|
|
15
|
+
|
|
16
|
+
## Parent Issue
|
|
17
|
+
|
|
18
|
+
Use a Parent Issue for a cohesive feature or outcome. It should contain summary, goals, in/out of scope, Sub-issue checklist, overall acceptance criteria, and source references.
|
|
19
|
+
|
|
20
|
+
## Sub-issue
|
|
21
|
+
|
|
22
|
+
Each Sub-issue must state:
|
|
23
|
+
|
|
24
|
+
- One task summary and context
|
|
25
|
+
- Concrete requirements
|
|
26
|
+
- Checklist of implementation tasks
|
|
27
|
+
- Testable Acceptance Criteria
|
|
28
|
+
- Hard dependencies (only when actually blocking)
|
|
29
|
+
- Technical/interface notes
|
|
30
|
+
- Assumptions and references
|
|
31
|
+
|
|
32
|
+
Prefer the repository's existing Issue template. Use the bundled templates only when none exists.
|
|
33
|
+
|
|
34
|
+
## Approval
|
|
35
|
+
|
|
36
|
+
Present Issues grouped by Parent. The user can approve/reject a whole group or edit/approve/reject individual items. Only approved drafts are created. Non-approved drafts remain local and are not automatically discarded.
|
|
37
|
+
|
|
38
|
+
Before creation, check GitHub for duplicates and current labels. Use a stable plan/task marker to make retry idempotent.
|
|
39
|
+
|
|
40
|
+
## Dependencies
|
|
41
|
+
|
|
42
|
+
Use GitHub native `Blocked by`/`Blocking` relationships. Do not create a hard block merely because two tasks are related. A documented stable interface contract can permit parallel FE/BE implementation. When an upstream task is excluded, preserve downstream approval but mark it locally blocked until the dependency is resolved.
|
|
43
|
+
|
|
44
|
+
## Follow-up Issues
|
|
45
|
+
|
|
46
|
+
After a task exhausts retries, propose a new follow-up Issue under the existing Parent. Include origin Issue, completed/remaining work, retry count, failure analysis, changed files, test results, redacted logs, and recovery context. Approval is required before creation.
|
|
47
|
+
|
|
48
|
+
Priority is impact-based for failures. Code-review improvements explicitly classified as high-priority follow-ups retain `high`. A failed task is not automatically high priority merely because it failed.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Orchestration Reference
|
|
2
|
+
|
|
3
|
+
## Choosing execution mode
|
|
4
|
+
|
|
5
|
+
Use Main Agent only for small or tightly coupled tasks. Use sequential execution for hard dependencies. Use Sub Agents only when meaningful independent tasks exist and the installed runtime supports safe delegation.
|
|
6
|
+
|
|
7
|
+
## Concurrency
|
|
8
|
+
|
|
9
|
+
Effective concurrency is the minimum of:
|
|
10
|
+
|
|
11
|
+
- User/Project configured cap
|
|
12
|
+
- Agent runtime capacity
|
|
13
|
+
- Safe concurrency after file-overlap/dependency analysis
|
|
14
|
+
- Resource budget
|
|
15
|
+
|
|
16
|
+
If no cap is configured, estimate conservatively. Never create workers simply to use available capacity.
|
|
17
|
+
|
|
18
|
+
## Isolation
|
|
19
|
+
|
|
20
|
+
Prefer verified native Agent isolation only if each worker receives a distinct writable workspace and Git remains Orchestrator-controlled. Otherwise create a separate Git Worktree per worker. Never share a writable worktree between workers.
|
|
21
|
+
|
|
22
|
+
## Authority
|
|
23
|
+
|
|
24
|
+
Orchestrator alone manages branches/worktrees, commits, pushes, Issues, Labels, dependencies, PRs, review resolution, and State. Workers only edit their assigned files and run tests. Workers do not commit or use GitHub write operations.
|
|
25
|
+
|
|
26
|
+
After verifying a work unit's diff, scope, relevant checks, and secret scan, the Orchestrator commits that unit before moving to unrelated work. Keep incomplete or blocked work uncommitted and report its state. One Issue may produce multiple commits when it contains multiple independently completed work units.
|
|
27
|
+
|
|
28
|
+
## Worker report (English only)
|
|
29
|
+
|
|
30
|
+
```markdown
|
|
31
|
+
## Task Report
|
|
32
|
+
|
|
33
|
+
- Issue: #123
|
|
34
|
+
- Status: completed | blocked | failed
|
|
35
|
+
|
|
36
|
+
### Summary
|
|
37
|
+
|
|
38
|
+
One or two sentences.
|
|
39
|
+
|
|
40
|
+
### Changed Files
|
|
41
|
+
|
|
42
|
+
- `path/to/file.ts`
|
|
43
|
+
|
|
44
|
+
### Tests
|
|
45
|
+
|
|
46
|
+
- Unit Tests: PASS
|
|
47
|
+
- Integration Tests: PASS
|
|
48
|
+
- Type Check: PASS
|
|
49
|
+
|
|
50
|
+
### Technical Decisions
|
|
51
|
+
|
|
52
|
+
- None.
|
|
53
|
+
|
|
54
|
+
### Known Issues
|
|
55
|
+
|
|
56
|
+
- None.
|
|
57
|
+
|
|
58
|
+
### Blockers
|
|
59
|
+
|
|
60
|
+
- None.
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Keep reports short. Do not include secrets or verbose chain-of-thought/reasoning. Report findings, decisions, test outcomes, and blockers only.
|
|
64
|
+
|
|
65
|
+
## Failure policy
|
|
66
|
+
|
|
67
|
+
A failure stops that task and its hard dependents; independent tasks continue. Default: initial attempt plus two retries. Stop early for repeated identical errors, unsafe state, missing permissions, or external prerequisites. After retry exhaustion, prepare a new follow-up Issue under the Parent and request approval.
|
|
68
|
+
|
|
69
|
+
## Integration
|
|
70
|
+
|
|
71
|
+
Orchestrator reads each report, checks the actual diff, validates scope, reruns tests, checks secret scanning, and records state. A worker's claim is not proof of successful validation.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Security, Deployment, Release, and Notifications
|
|
2
|
+
|
|
3
|
+
## Secret scanning
|
|
4
|
+
|
|
5
|
+
Reuse the project's existing scanner. If none exists, propose a scanner and obtain approval before installation. Scan staged changes before commit, again before push/PR, and in CI. A likely real secret blocks commit/push. Redact values from all logs/reports. If a secret was pushed, advise immediate revocation/rotation; removing the line is insufficient.
|
|
6
|
+
|
|
7
|
+
## Hooks
|
|
8
|
+
|
|
9
|
+
Reuse existing hooks. Propose installation/change only with approval. Bypass only a diagnosed tool/environment problem, recording command and reason. Never bypass new code-caused failures or permanently disable hooks.
|
|
10
|
+
|
|
11
|
+
## Branch protection
|
|
12
|
+
|
|
13
|
+
Inspect existing rules and propose changes. Apply only after user approval. Never silently modify team repository settings.
|
|
14
|
+
|
|
15
|
+
## Deployment
|
|
16
|
+
|
|
17
|
+
After merge, inspect configured deployment and Health Check results. Retry transient failures within bounds. Ask for missing user-controlled settings. If Health Check fails, stop further deployment actions and report. Rollback requires user approval.
|
|
18
|
+
|
|
19
|
+
## Release
|
|
20
|
+
|
|
21
|
+
Existing project release convention wins. If absent, use SemVer. Analyse Conventional Commits and Breaking Changes, draft CHANGELOG and Release Notes, show proposed version and obtain approval before Tag/GitHub Release creation.
|
|
22
|
+
|
|
23
|
+
## Notifications
|
|
24
|
+
|
|
25
|
+
Notify only on important events: overall start/finish, approval needed, repeated worker failure, unrecoverable CI failure, PR ready/Merge waiting, and deployment failure. Session/CLI output is default. External notification providers are optional adapters and must not be required for core operation. No telemetry.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# State and Recovery Reference
|
|
2
|
+
|
|
3
|
+
## Source of truth
|
|
4
|
+
|
|
5
|
+
GitHub is authoritative for remote Issue, dependency, PR, Merge, and CI states. Local State stores execution detail: plan DAG, workers, worktrees, file scope, retry counts, checkpoints, report digests, approval records, and cache references.
|
|
6
|
+
|
|
7
|
+
## Storage
|
|
8
|
+
|
|
9
|
+
- Project Config: `.github-convention/config.yaml` (YAML, Git-tracked)
|
|
10
|
+
- Conventions: `.github-convention/conventions/` (Git-tracked)
|
|
11
|
+
- Cache: `.github-convention/cache/` (JSON, ignored)
|
|
12
|
+
- Active State: `.github-convention/state/active/` (JSON, ignored)
|
|
13
|
+
- Archive: `.github-convention/state/archive/` (JSON, ignored)
|
|
14
|
+
- Logs: `.github-convention/logs/` (redacted, ignored)
|
|
15
|
+
|
|
16
|
+
One State JSON file per execution plan/Parent run. Only Orchestrator writes it. Save after every meaningful state transition using atomic write.
|
|
17
|
+
|
|
18
|
+
## Locking
|
|
19
|
+
|
|
20
|
+
Acquire a project-level exclusive lock before any mutating workflow. Record PID, host, run ID, process start, and timestamp. Never remove a lock unless ownership is verified stale. If another live Orchestrator holds it, return `LOCK_BUSY`; do not concurrently mutate worktrees/state.
|
|
21
|
+
|
|
22
|
+
## Resume
|
|
23
|
+
|
|
24
|
+
1. Read and validate Local State.
|
|
25
|
+
2. Fetch current GitHub Issue/dependency/PR state.
|
|
26
|
+
3. Reconcile remote facts into local state.
|
|
27
|
+
4. Skip completed tasks verified by remote state.
|
|
28
|
+
5. Inspect in-progress worktree and diffs before resuming.
|
|
29
|
+
6. Preserve commits/uncommitted work.
|
|
30
|
+
7. If approval cannot be verified, ask again.
|
|
31
|
+
8. If ownership or status is ambiguous, stop and report.
|
|
32
|
+
|
|
33
|
+
## Archive
|
|
34
|
+
|
|
35
|
+
Move completed runs to archive. Default retention is 30 days, configurable globally and per project. Run cleanup on the next CLI invocation; do not run a background daemon. Never delete active runs. Allow inspect/restore.
|
package/README.md
DELETED