fix(#190): remove Jira remnants and add issues:write to custom agent guide

[fullsend-ai-coder]

Remove the Jira code path from the pre-script example (which left an orphaned elif after PR fullsend-ai#2568 removed Jira support), consolidate permissions into a single block with contents:read, id-token:write, and issues:write, and drop the now-unused issue_source workflow input.

---

Closes #190

Post-script verification

• Branch is not main/master (agent/190-fix-docs-building-custom-agents)
• Secret scan passed (gitleaks — f96750babbed5ada406a9ae04e8068449701d9c7..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

Review

Findings

Low

• [permission-expansion] docs/guides/user/building-custom-agents.md:345 — The diff adds issues: write to the main agent workflow example (Step 7), but the pre-script only uses gh issue view (a read operation) and the example post-script does not write to issues. At most issues: read is needed for the example as written. Granting issues: write in example code that users will copy violates least-privilege.
  Remediation: Replace issues: write with issues: read in the main workflow example, since only gh issue view is used. Add an inline comment noting that users should upgrade to issues: write if their post-script creates or updates issues.

---

Labels: PR fixes documentation bugs in user guide

Previous run

Review

Findings

Medium

• [edge-case] docs/guides/user/building-custom-agents.md:265 — The pre-script example references $REPO_FULL_NAME, but this variable is never defined in the workflow env block (Step 7) or in the harness runner_env (Step 2). With set -euo pipefail, the script will fail immediately with an unbound variable error. This was pre-existing (the old elif branch had the same issue), but the PR promotes it from a conditional branch to unconditional code, making it a guaranteed failure for anyone who copies the example verbatim.
  Remediation: Replace "$REPO_FULL_NAME" with "$GITHUB_REPOSITORY" (automatically available in GitHub Actions), or add REPO_FULL_NAME: ${{ github.repository }} to the workflow env block.

Low

• [stale-reference] docs/guides/user/building-custom-agents.md:223 — The policy design principles section still references Jira ("Never allow Jira/internal APIs from the sandbox...") while the PR removes all Jira examples from the guide. Consider generalizing to "Never allow external issue-tracking APIs from the sandbox. All external reads happen in pre-scripts; all writes happen in post-scripts."
• [permission-expansion] docs/guides/user/building-custom-agents.md:345 — issues: write is added to the main workflow template's permissions block, but the example workflow contains no code that writes to issues. The GH_TOKEN with this permission flows through the harness and potentially into the sandbox. The slash-command dispatch workflow later in the guide already correctly scopes issues: write to just the dispatch job. Consider removing it from the main workflow or adding a comment explaining when it is needed.

[guyoron1]

/fs-review

[fullsend-ai-review]

[low] permission-expansion

The diff adds issues: write to the main agent workflow example (Step 7), but the pre-script only uses gh issue view (a read operation) and the example post-script does not write to issues. At most issues: read is needed for the example as written. Granting issues: write in example code that users will copy violates least-privilege.

Suggested fix: Replace issues: write with issues: read in the main workflow example, since only gh issue view is used. Add an inline comment noting that users should upgrade to issues: write if their post-script creates or updates issues.