Skip to content

setup.md

Latest commit

 

History

History
222 lines (159 loc) · 8.57 KB

setup.md

File metadata and controls

222 lines (159 loc) · 8.57 KB

Getting Started

Prerequisites

Token & Permissions Requirements

Agentic workflows run as GitHub Actions. The following tokens/secrets are needed:

For local development (gh CLI)

# Standard auth
gh auth login

# Add project scopes (required for launch tracker data fetching)
gh auth refresh -s read:project,project

For GitHub Actions (repository secrets)

Secret Required Purpose
GITHUB_TOKEN Automatic Default Actions token — used for issue/PR reads and safe-outputs writes
COPILOT_GITHUB_TOKEN Yes (for Copilot engine) Token for the AI engine. Set up via gh aw init
AW_TOKEN Yes PAT with read:project scope — used by pre-steps to fetch project data via GraphQL

The GITHUB_TOKEN needs these permissions (configured in the workflow frontmatter):

  • contents: read — read repo files (policy files, scripts)
  • issues: read — read issues and sub-issues
  • pull-requests: read — read linked PRs
  • discussions: read — read existing discussions

Write operations (creating discussions) are handled by safe-outputs in a separate secured job — the agent job itself stays read-only.

Setting up AW_TOKEN

The pre-step script fetches data from GitHub Projects via GraphQL, which requires the read:project scope. The default GITHUB_TOKEN doesn't include this scope, so you need a PAT:

  1. Create a fine-grained PAT at github.com/settings/tokens
    • Repository access: your agentics-beyond-code repo
    • Permissions: Projects → Read-only
  2. Or create a classic PAT with the read:project scope
  3. Add it as a repository secret:
gh secret set AW_TOKEN
# Paste your PAT when prompted

Installation

# Install the GitHub CLI (if not already installed)
brew install gh   # macOS
# See https://cli.github.com/ for other platforms

# Authenticate with required scopes
gh auth login
gh auth refresh -s read:project,project

# Install the Agentic Workflows extension
gh extension install github/gh-aw

# Add project scopes (needed for launch tracker integration)
gh auth refresh -s read:project,project

Setting Up Your Repository

1. Clone and initialize

gh repo clone chrizbo/agentics-beyond-code
cd agentics-beyond-code
gh aw init

2. Create a Launch Tracker project

Create a GitHub Project (Projects V2) to track your launches. Add these custom fields:

Field Type Options
Phase Single select Team, Alpha, Beta, GA
Target Date Date —
Launch Type Single select Major, Minor, Patch, Internal
Risk Level Single select Low, Medium, High, Critical

4. Create an Intake Triage project

Create a second GitHub Project (Projects V2) to track incoming feature requests and bug reports. Add these custom fields:

Field Type Options
RICE Score Text —
Request Type Single select Feature Request, Bug Report
Kano Category Single select Must-be, One-dimensional, Attractive, Indifferent
RICE Level Single select High, Medium, Low

Set up the Status field with these options:

Status Purpose
Needs Triage (default) New items awaiting triage
Needs More Info Incomplete submissions — bot has asked follow-up questions
Triaged Fully scored and assessed
Duplicate Duplicate of an existing issue
Accepted Accepted into the backlog
Deferred Not now — revisit later

Important: Set "Needs Triage" as the default status value so items added by workflows are always visible in your views, even if the workflow fails to set the status.

Create two views:

  • Needs Triage — filter: status:"Needs Triage","Needs More Info"
  • Triaged — filter: status:Triaged,Duplicate,Accepted,Deferred

5. Create labels

The following labels are used by workflows. Create them in your repository:

Issue type labels:

  • initiative — strategic initiative
  • launch — shippable launch milestone
  • epic — workstream within a launch
  • blocker — blocking issue

State labels:

  • at-risk — launch is at risk
  • ready-for-review — ready for domain team review

Domain tracking labels (workflow-managed, ai: prefix):

  • ai:needs:security, ai:needs:privacy, ai:needs:accessibility, ai:needs:responsible-ai
  • approved:security, approved:privacy, approved:accessibility, approved:responsible-ai

Compliance labels (workflow-managed, ai: prefix):

  • ai:compliance-review — marks compliance review sub-issues (auto-created by workflow)

GTM labels (workflow-managed, ai: prefix):

  • ai:gtm — marks go-to-market content sub-issues (changelog drafts, roadmap items)

Transcript labels (workflow-managed, ai: prefix):

  • ai:meeting-discussed — marks issues that were discussed in a meeting transcript (auto-created by workflow)

Report labels:

  • report, launch-readiness

Intake triage labels:

  • triage-needed — marks an issue for automated triage (auto-applied by the intake issue template)
  • triaged — triage complete (added by workflow)
  • needs-more-info — submission is incomplete (added by workflow)
  • duplicate — duplicate of an existing issue (added by workflow)
  • rice:high, rice:medium, rice:low — RICE score level (added by workflow)
  • kano:must-be, kano:one-dimensional, kano:attractive, kano:indifferent — Kano category (added by workflow)
  • aligns-with-current — aligns with an active initiative or launch (added by workflow)

6. Create issues using templates

Use the built-in issue templates to create properly structured issues:

  • Initiative — for strategic goals spanning multiple launches
  • Launch — for shippable milestones (the primary unit of work)
  • Intake Request — for submitting new feature requests or bug reports for triage

Link launches as sub-issues of initiatives, and epics/tasks as sub-issues of launches.

7. Add issues to your project

Add your initiative, launch, epic, and task issues to the Launch Tracker project. Set the Phase and Target Date custom fields on each launch.

8. Create directories for decision log and transcript workflows

# Create the directories (with .gitkeep so they're tracked)
mkdir -p decisions transcripts
touch decisions/.gitkeep transcripts/.gitkeep
git add decisions/.gitkeep transcripts/.gitkeep
git commit -m "Add decisions and transcripts directories"
  • /decisions/ — Decision record markdown files are created here by the Decision Log workflow via PR
  • /transcripts/ — Drop .txt or .vtt meeting transcripts here to trigger the Transcript Processor workflow

9. Compile and run workflows

# Compile all workflows
gh aw compile

# Run the launch readiness report
gh aw run launch-readiness

# View logs
gh aw logs launch-readiness

Customizing Policies

Policy files live in .github/policies/ and control how workflows assess your launches. Edit them to match your team's standards:

Policy changes take effect on the next workflow run — no recompilation needed.

Updating the Project Number

The fetch-launch-data.sh script defaults to project number 1. If your project has a different number, update the steps: section in the workflow file:

steps:
  - name: Fetch launch data
    run: |
      ./.github/scripts/fetch-launch-data.sh "${{ github.repository_owner }}" YOUR_NUMBER launch-data.json

Then recompile with gh aw compile.