[issues] Reuse issue metadata and sync linked pull requests (#152) (#153)

* [issues] Reuse existing issue and project metadata (#152)

* Update wiki submodule pointer for PR #153

* [issues] Sync linked issue metadata onto pull requests (#152)

* [issues] Clarify project access recovery guidance (#152)

* [issues] Add iteration and backfill guidance (#152)

* [issues] Generalize inferable project-field guidance (#152)

* [ci] Extract workflow automation into local actions (#152)

* [wiki] Split preview and maintenance workflows (#152)

* [reports] Checkout before local verify actions (#152)

* [wiki] Split preview and maintenance entry workflows (#152)

* [docs] Align automation docs and agent guidance (#152)

* [agents] Refresh automation audit prompts (#152)

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.agents/agents/agents-maintainer.md

@@ -21,6 +21,9 @@ accurate setup, workflow, testing, and contribution instructions.
 - Preserve the repository's existing instruction structure and terminology.
 - Cross-check referenced commands, paths, and generated artifacts before
   finalizing updates.
+- Cross-check workflow entrypoints in `.github/workflows/`, reusable local
+  actions in `.github/actions/`, and packaged consumer wrappers in
+  `resources/github-actions/` before documenting automation behavior.
 - Add or refresh notable repository references such as `README.md`, `docs/`,
   workflow files, and other canonical local entrypoints when they help agents
   navigate the project.
@@ -29,6 +32,8 @@ accurate setup, workflow, testing, and contribution instructions.
 
 - A PR changes setup, development, testing, sync, or contribution workflows
   documented in `AGENTS.md`.
+- A PR refactors GitHub Actions by moving logic between workflow wrappers and
+  local actions, or splits one workflow into multiple entrypoints.
 - The repository adds, removes, or renames packaged skills or project agents.
 - `AGENTS.md` drifted from the current repository behavior.
 
@@ -37,6 +42,8 @@ accurate setup, workflow, testing, and contribution instructions.
 - Do not duplicate or replace `README.md` when a human-facing doc update is the
   actual need.
 - Do not invent workflows or commands that are not present in the checkout.
+- Do not ignore repo-local automation assets just because consumer repositories
+  only receive wrapper workflows; both surfaces can change the right guidance.
 - Do not rewrite unrelated docs trees when only `AGENTS.md` needs maintenance.
 
 ## Primary Skill

.agents/agents/consumer-sync-auditor.md

@@ -21,17 +21,24 @@ wiki/bootstrap assets.
 - Check whether changes affect packaged role prompts as well as packaged skills.
 - Call out downstream bootstrap, workflow, wiki, or onboarding implications.
 - Verify that packaged defaults remain coherent with sync behavior.
+- Distinguish between consumer-facing workflow wrappers in
+  `resources/github-actions/` and repository-only local actions in
+  `.github/actions/`, and trace when changes in one imply updates to the other.
 - Surface when docs or README updates are needed for consumer adoption.
 
 ## Use When
 
 - A change touches `resources/`, `.github/workflows/`, `.agents/skills`,
-  `.agents/agents`, `.editorconfig`, wiki automation, or `dev-tools:sync`.
+  `.agents/agents`, `.editorconfig`, wiki automation, `.github/actions/`, or
+  `dev-tools:sync`.
 - A PR may affect how consumer repositories adopt or refresh DevTools assets.
 
 ## Boundaries
 
 - Do not treat every repository-only change as a consumer sync concern.
+- Do not assume `.github/actions/` changes are internal-only; check whether the
+  consumer-facing wrappers, AGENTS guidance, or sync docs now describe the wrong
+  automation shape.
 - Do not replace the implementation workflow; this role is an impact auditor,
   not a separate execution path.
 

.agents/agents/issue-editor.md

@@ -17,6 +17,14 @@ issues for the current repository.
 - Draft clear issue titles and English issue bodies.
 - Refine problem statements, scope, non-goals, and acceptance criteria.
 - Maintain issue lifecycle actions such as comments, updates, and closure notes.
+- Choose the most appropriate existing issue metadata the repository already
+  supports, including type, labels, project placement, and adjacent issue
+  relationships when they can be inferred safely.
+- Fill any existing project field that can be inferred with high confidence
+  from the issue scope, repository workflow, or linked pull-request history.
+- When project metadata matters but GitHub CLI lacks project scope, trigger the
+  refresh flow and tell the user they MAY need to finish the browser-and-code
+  verification step before project access becomes available.
 - Keep issue language aligned with Fast Forward command, docs, workflow, and
   packaging vocabulary.
 

.agents/agents/quality-pipeline-auditor.md

@@ -22,6 +22,9 @@ single command in isolation.
 - Recommend the smallest verification set that still covers pipeline risk.
 - Watch for drift between command behavior, workflow automation, and generated
   outputs.
+- Watch for workflow refactors that move quality-pipeline behavior into local
+  GitHub actions or split one workflow into preview, publication, and
+  maintenance entrypoints.
 - Highlight when a change should update tests, docs, or contributor guidance
   together.
 

.agents/skills/github-issues/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: github-issues
-description: Draft, create, update, comment on, and close GitHub issues for Fast Forward repositories. Use when an agent needs to turn a brief feature, bug, or task prompt into a production-ready issue, refine existing issue content, publish or update an issue on GitHub, manage labels or milestones, add issue comments, or close tracked work without leaving the local workflow.
+description: Draft, create, update, comment on, and close GitHub issues for Fast Forward repositories. Use when an agent needs to turn a brief feature, bug, or task prompt into a production-ready issue, refine existing issue content, publish or update it on GitHub, manage existing metadata such as labels, types, milestones, projects, and project fields, add issue comments, or close tracked work without leaving the local workflow.
 ---
 
 # Fast Forward GitHub Issues
@@ -24,12 +24,21 @@ Use this skill for the full Fast Forward issue lifecycle: draft implementation-r
 - Include CLI examples, flags, paths, generated artifacts, or error cases when the change touches commands, automation, or reports.
 - Add explicit non-goals when the prompt could expand into multiple initiatives.
 - Ask follow-up questions only when a missing fact would materially change the issue type, acceptance criteria, or target issue. Otherwise make the smallest safe assumption and state it briefly.
+- When publishing or updating an issue, explicitly state which metadata was applied or intentionally omitted: issue type, labels, milestone, project assignment, project field values, and related open issues.
 
 ## Fast Forward Defaults
 
 - Prefer the current repository checkout when the user asks about "this repo" or "this project".
 - Use `gh api` for GitHub write operations.
 - Prefer issue types over labels for primary categorization when the organization supports them.
+- Reuse only issue types, labels, milestones, projects, and project field options that already exist in the target repository or organization.
+- Prefer filling the maximum useful metadata that can be inferred safely from the issue scope and the available GitHub configuration.
+- Do not force weak labels, milestones, project assignments, or project field values when the fit is unclear.
+- When project metadata matters and GitHub CLI lacks project scope, try `gh auth refresh -h github.com -s read:project -s project` and tell the user they MAY need to complete the browser-and-code flow.
+- When no suitable repository or organization project exists, you MAY suggest copying the Fast Forward template project at `https://github.com/orgs/php-fast-forward/projects/2`.
+- When a project exposes any field whose value can be inferred with a high degree of confidence, prefer filling it instead of leaving it blank by default.
+- Support backfill runs for older issues with missing metadata, but only fill fields that are currently unset unless the user explicitly asks for correction.
+- When a new issue appears materially related to another open issue, add that relationship instead of leaving the issues disconnected.
 - Treat command or controller layers as orchestration only when drafting implementation issues.
 - Prefer dedicated classes for input resolution, domain logic, processing, and output rendering when the change is non-trivial.
 - Call out test, README, docs, wiki, sync, or generated report updates when the change clearly affects them.
@@ -45,7 +54,7 @@ Use this skill for the full Fast Forward issue lifecycle: draft implementation-r
 | Start from a reusable issue body structure | [references/templates.md](references/templates.md) |
 | Paste the correct acceptance-criteria block | [references/architectural-criteria.md](references/architectural-criteria.md) |
 | Create, update, comment on, or close an issue | [references/operations.md](references/operations.md) |
-| Choose issue types, labels, assignees, and milestones | [references/metadata.md](references/metadata.md) |
+| Choose issue types, labels, assignees, milestones, projects, and related issue metadata | [references/metadata.md](references/metadata.md) |
 | Perform the final quality and mutation-safety pass | [references/review-checklist.md](references/review-checklist.md) |
 
 ## Anti-patterns
@@ -57,3 +66,4 @@ Use this skill for the full Fast Forward issue lifecycle: draft implementation-r
 - Do not ask exploratory questions when repository conventions already provide a safe default.
 - Do not publish a placeholder issue body or mutate GitHub without restating the target issue first.
 - Do not split drafting and publication into separate local skills when this workflow already covers both.
+- Do not invent labels, issue types, milestones, projects, project field values, or issue links that are not already supported by the target repository context.

.agents/skills/github-issues/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Fast Forward GitHub Issues"
-  short_description: "Draft and manage Fast Forward GitHub issues"
-  default_prompt: "Use $github-issues to draft, create, or update this Fast Forward GitHub issue."
+  short_description: "Draft and manage Fast Forward GitHub issues with existing repository metadata"
+  default_prompt: "Use $github-issues to draft, create, or update this Fast Forward GitHub issue and apply the most appropriate existing repository metadata."

.agents/skills/github-issues/references/context.md

@@ -18,6 +18,20 @@ Useful check:
 gh auth status
 ```
 
+If the request may require project assignment or project-field updates, also
+confirm the active token can read and write project metadata. A token that can
+mutate issues may still be missing `read:project` or `project` scope.
+
+When project scope is missing but project placement or project-field updates
+matter to the request, try to refresh authentication before giving up:
+
+```bash
+gh auth refresh -h github.com -s read:project -s project
+```
+
+Tell the user that GitHub CLI MAY open a browser and ask them to enter a
+verification code before the refreshed token is granted project access.
+
 ## Existing Issue Resolution
 
 For updates or comments:
@@ -29,6 +43,7 @@ For creates:
 
 - check whether an obvious duplicate already exists when the prompt strongly suggests current tracked work
 - if the repository already has a canonical issue for the request, update or comment on it instead of creating another one
+- inspect open issues when the request appears adjacent to current tracked work so related issues can be linked intentionally
 
 ## Output Requirement
 

.agents/skills/github-issues/references/metadata.md

@@ -1,6 +1,18 @@
 # Metadata Guidance
 
-Use this reference when the issue needs labels, types, assignees, or milestones.
+Use this reference when the issue needs labels, types, assignees, milestones,
+project assignment, project field values, or issue relationships.
+
+## General Rule
+
+- Reuse only metadata that already exists in the target repository or
+  organization.
+- Prefer the maximum useful metadata that can be inferred safely from scope and
+  repository context.
+- Leave a field unset when the fit is weak, ambiguous, or unsupported by the
+  available token.
+- Never create new labels, issue types, projects, project field options, or
+  milestones as part of normal issue drafting or publication.
 
 ## Issue Types
 
@@ -20,6 +32,9 @@ gh api graphql \
   --jq '.data.organization.issueTypes.nodes[].name'
 ```
 
+Select the closest existing type for the issue scope. Do not downgrade to a
+label-only strategy when a fitting issue type exists.
+
 ## Labels
 
 Use labels for secondary categorization, not as a replacement for issue type when a type exists.
@@ -31,11 +46,102 @@ Examples that may still be useful:
 - `help wanted`
 - `question`
 
+Choose labels only from the existing repository label set. Add them when they
+materially improve categorization, not as a reflex.
+
+Discovery example:
+
+```bash
+gh label list --repo {owner}/{repo} --limit 200
+```
+
 ## Milestones and Assignees
 
 - Set a milestone only when the repository is actively using milestone-based planning.
 - Assign users only when the request or repository workflow clearly calls for it.
 
+Milestone discovery example:
+
+```bash
+gh api repos/{owner}/{repo}/milestones
+```
+
+If there are no milestones, or none clearly fit the scope, leave the issue
+without one.
+
+## Projects
+
+When the repository or organization uses Projects, prefer adding the issue to
+the most appropriate existing project instead of leaving project assignment
+empty by default.
+
+Project discovery example:
+
+```bash
+gh api graphql \
+  -f query='{ organization(login: "ORG") { projectsV2(first: 20) { nodes { id title number closed } } } }'
+```
+
+If project access is unavailable, first try to refresh GitHub CLI scopes:
+
+```bash
+gh auth refresh -h github.com -s read:project -s project
+```
+
+Warn the user that this command MAY open a browser and ask them to type a
+verification code before project access is granted.
+
+If no existing repository or organization project clearly fits, omit the
+project assignment instead of guessing. When the repository and organization do
+not appear to have any usable project at all, you MAY suggest copying the Fast
+Forward template project as a starting point:
+
+```text
+https://github.com/orgs/php-fast-forward/projects/2
+```
+
+Treat that suggestion as optional guidance for the user, not as a project you
+create automatically.
+
+## Project Fields
+
+When a selected project exposes fields whose values can be inferred with a high
+degree of confidence, attempt to populate them instead of leaving them blank by
+default. Common examples include `Status`, `Priority`, and `Size`, but the same
+rule applies to any existing project field that has a clear fit for the issue.
+
+Common guidance:
+
+- `Status`: pick the nearest lifecycle state, often `Backlog` or `Ready` for a
+  newly created issue.
+- `Priority`: prefer the lowest confident priority instead of inflating urgency.
+- `Size`: choose a rough estimate only when the issue scope supports it.
+- Other fields: populate them only when the issue scope, repository context, or
+  linked pull-request history makes the right value genuinely clear.
+
+Backfill guidance:
+
+- Support backfill for older issues that are missing project metadata.
+- Only backfill fields that are currently unset or obviously incomplete.
+- Do not overwrite existing project-field values during a backfill pass unless
+  the user explicitly asks for correction.
+
+Do not invent new field options, and do not force a value when no safe choice
+is evident.
+
+## Related Issues
+
+When a newly drafted issue appears materially related to an existing open issue,
+record that relationship instead of leaving the issues disconnected.
+
+Examples of useful relationships:
+
+- dependency or blocker
+- follow-up or split from a larger tracked task
+- scope overlap that reviewers should see together
+
+Avoid speculative or noisy links when the relationship is weak.
+
 ## Title Guidance
 
 - Keep the title specific and actionable.

.agents/skills/github-issues/references/operations.md

@@ -21,6 +21,9 @@ Add metadata flags only when needed:
 -f milestone=1
 ```
 
+After creation, apply project assignment, project field values, or issue links
+through follow-up mutations when the repository context supports them.
+
 ## Update Issue
 
 ```bash
@@ -33,6 +36,40 @@ gh api repos/{owner}/{repo}/issues/{number} \
 
 Only include the fields that should change.
 
+## Add Issue to an Existing Project
+
+```bash
+gh api graphql \
+  -f query='mutation($project:ID!, $content:ID!) { addProjectV2ItemById(input: {projectId: $project, contentId: $content}) { item { id } } }' \
+  -f project='PROJECT_ID' \
+  -f content='ISSUE_NODE_ID'
+```
+
+## Set an Existing Project Field Value
+
+For single-select fields such as `Status`, `Priority`, `Size`, or any other
+existing single-select field with a safe inferred value:
+
+```bash
+gh api graphql \
+  -f query='mutation($project:ID!, $item:ID!, $field:ID!, $option:String!) { updateProjectV2ItemFieldValue(input: {projectId: $project, itemId: $item, fieldId: $field, value: {singleSelectOptionId: $option}}) { projectV2Item { id } } }' \
+  -f project='PROJECT_ID' \
+  -f item='ITEM_ID' \
+  -f field='FIELD_ID' \
+  -f option='OPTION_ID'
+```
+
+The same principle applies to any other supported project field type: only
+write values that can be inferred confidently from the issue scope, repository
+workflow, or linked pull-request history.
+
+## Add a Related-Issue Link
+
+When the repository supports issue relationships, prefer the official GitHub
+relationship mutation or connector path available in the environment. If that
+surface is unavailable, explicitly mention the related issue in the body or an
+issue comment rather than silently dropping the relationship.
+
 ## Add Comment
 
 ```bash
@@ -56,3 +93,7 @@ gh api repos/{owner}/{repo}/issues/{number} \
 - Restate the target issue before mutating it.
 - Prefer full body replacement only when the body is being intentionally rewritten.
 - Use comments for incremental updates that should preserve the issue description.
+- For new issues, prefer applying metadata immediately after creation so the
+  issue lands in GitHub with a complete and reviewable state.
+- For backfill passes, update only missing metadata by default and avoid
+  rewriting fields that already carry intentional values.

.agents/skills/github-issues/references/review-checklist.md

@@ -12,6 +12,7 @@ Use this checklist before finalizing issue content or mutating GitHub.
 - Repository-specific terms, commands, directories, or artifacts are named precisely.
 - Non-goals are present when the request could easily expand in scope.
 - Tests, docs, README, wiki, sync, or reports are called out when the change obviously affects them.
+- The chosen metadata strategy is explicit about what should be applied versus omitted.
 - Assumptions are minimal and explicitly stated when inference was necessary.
 - The final output contains no meta commentary about prompting or the drafting process.
 
@@ -22,6 +23,13 @@ Use this checklist before finalizing issue content or mutating GitHub.
 - The target issue number is correct for updates, comments, or closure.
 - The title and body are final or intentionally partial.
 - Metadata changes are explicit and necessary.
+- Applied labels, issue type, milestone, project assignment, project field
+  values, and issue relationships come only from metadata that already exists.
+- Any project field that was left empty despite being inferable has a clear
+  reason, not an accidental omission.
+- Backfill writes touched only fields that were previously unset, unless the
+  user explicitly asked for metadata correction.
+- Project or milestone fields were left empty only for a clear reason, not by omission.
 - A duplicate issue is not being created accidentally.
 - The final response will include the issue number and URL.