github-issue-creation

Files (2)

• SKILL.md
• github_issue_creation_spec.md · references/

SKILL.md (first lines)

# GitHub Issue Creation (ACE = Appforge Coding Engine)

## Overview

Follow the ACE issue creation workflow to open issues and set project board status across repos.

## Your Role

You are helping a human create issues that will be processed by an autonomous coding agent.
You must:
1. Help the human plan well-formed issues.
2. Present the proposed issues for human approval.
3. After approval, use GitHub MCP to create/update issues.
4. After creation, add issues to the **your-org / your-project** project board.

## Workflow

1. Locate the target repo by reading its `project_architecture.md` to confirm where the issue belongs.
2. Create a discrete, modular issue focused on a single task or goal.
3. Capture dependencies in the issue description and use GitHub issue relationships to link them.
4. For `your-terraform-repo` update issues, add an explicit instruction to run the `terraform-apply` skill at the end of the work.
5. When a new secret is added to Secret Manager via Terraform, create a follow-up issue assigned to `repo-owner` to add the secret value as a version, including this command in the issue: `printf %s \"$SECRET_VALUE\" | gcloud secrets versions add SECRET_NAME --data-file=-`.
6. If opening follow-up work from planning outputs, align issue boundaries with the generated `ISSUES.json` entries and preserve dependency intent.
7. If planning is expected to create issues automatically, confirm the session is in `plan_and_create_issues` mode (not `plan_only`).
8. For manual planning follow-up issues, include the same deterministic IDs and dependency order from `ISSUES.json` (or preserve the blocker ordering explicitly in the body).
9. Choose the execution label: `developer`, `agent:local`, or `agent:remote` based on who/where the work must happen.
10. Apply exactly one difficulty label: `difficulty:easy`, `difficulty:medium`, or `difficulty:hard`.
11. Present the issue(s) to the human for approval.
12. After approval, create/update the issue(s) using `github-mcp`.
13. Set project status to `Backlog` using `appforge-mcp`.

## Issue Requirements

Every issue MUST include:
1. Clear title (specific, actionable)
2. Target repository (explicitly stated in body)
3. Detailed description (what + why)
4. Acceptance criteria (testable)
5. Context (links, docs, background)
6. Dependencies (blocked-by/depends-on) using issue IDs for `depends_on` contracts when derived from planning payloads.

## Planning Issue Payload Contract

When creating issues from planner outputs, these fields are expected in generated `ISSUES.json`:
- `issues` array entries with:
  - `id` (string, stable, unique within session)
  - `repo` (string in `owner/repo` form)
  - `title`
  - optional `description`
  - optional `depends_on` (array of prior issue ids)
- Planner enforces acyclic dependencies.
- The issue writer runs dependencies topologically and attaches blocker references in body as `Blocked By`.
- Session event checks for validation after running:
  - `issues_written` event with `requested_count` and `created` list
  - final `done` event with `issue_created_count`
- Lifecycle stage used by the worker is `planning_issue_writer`.

When writing manual split issues from planning guidance, keep repo-scoped context high-signal, and preserve dependency intent in titles/body/links.

## Choosing the Right Repository (Multi-Repo Guidance)

- Prefer one repo per issue. Split cross-repo work into sub-issues.
- Defaults by area:
  - Infra/Cloud: `your-terraform-repo`
  - MCP/tools: `<project>-mcp`
  - Frontend: `<project>-web` or `<project>-frontend`
  - Orchestration/Backend: main service repo
  - Data/DB migrations: owning service repo

## Issue Format (Use This)

```markdown
## Target Repository
[exact-repo-name]

## Description
[2-3 sentences describing what needs to be done]

[Additional context, background, or rationale]

## Acceptance Criteria
- [ ] Specific, testable requirement 1
- [ ] Specific, testable requirement 2
- [ ] Specific, testable requirement 3
- [ ] Code follows project conventions
- [ ] Tests pass (if applicable)
- [ ] No console errors or warnings

## Implementation Notes
[Optional: specific files to modify, patterns to follow, or constraints]

## Related Issues
[Links to related issues, PRs, or documentation]
```

## Title Format

`[Action] [What] [Where/Context]`

Examples:
- "Add dark mode support to frontend-repo"
- "Fix authentication bug in auth-service"
- "Implement caching layer in api-gateway"

## Agent Type Assessment

- `agent:remote` (default): standard code changes, no local access needed
- `agent:local`: needs local machine access (DB, files, device)
- `developer`: human-only actions (DNS, vendor dashboards)

## Difficulty Assessment

- Easy: small fixes/docs
- Medium: feature work/integrations
- Hard: architecture changes/complex work

## Quality Checklist

- Title is clear and specific

From Day-in-the-Country-LLC/appforge-poc, MIT.

More from Day-in-the-Country-LLC/appforge-poc