SGAI Goal Authoring

Compose GOAL.md files for SGAI workspaces through interactive conversation.

When to Use

• User says "start a new feature/project/fix"
• User describes work to be done in an SGAI-managed repo
• User asks to "create a goal" or "set up SGAI"

Process

flowchart TB
    detect["Detect tech stack"]
    prefs["Load/ask model preferences"]
    describe["Ask: What do you want to accomplish?"]
    criteria["Draft success criteria"]
    confirm["Show preview, ask for confirmation"]
    backup["Backup existing GOAL.md if present"]
    write["Write GOAL.md"]

    detect --> prefs --> describe --> criteria --> confirm --> backup --> write

1. Detect Tech Stack

Scan the repository for files and choose appropriate agents:

Multiple stacks combine (e.g., Go + React = both agent chains).

Special-purpose agents (add when relevant):

• c4-code, c4-component, c4-container, c4-context - Architecture documentation
• skill-writer - Creating SGAI skills
• snippet-writer - Reusable code patterns
• webmaster - Marketing sites and landing pages
• project-critic-council - Multi-model consensus review

2. Load or Ask Model Preferences

Check .sgai/preferences.json for saved preferences:

{
  "models": {
    "coordinator": "anthropic/claude-opus-4-6 (max)",
    "default": "anthropic/claude-opus-4-6"
  }
}

If no preferences exist, ask:

"What model should I use for SGAI agents? (e.g., anthropic/claude-opus-4-6)"

Save response to .sgai/preferences.json for future use.

3. Ask for Goal Description

Ask conversationally:

"What do you want to accomplish?"

Listen for:

• Feature: "add", "build", "create", "implement"
• Fix: "bug", "fix", "broken", "error", "issue"
• Project: "new project", "set up", "initialize"

If unclear, ask:

"Is this a new feature, a bug fix, or a new project?"

4. Draft Success Criteria

Transform the description into outcome-based success criteria:

User says: "Add user authentication with OAuth"

Draft as:

- [ ] Users can sign in with OAuth providers
- [ ] Authenticated sessions persist across browser restarts
- [ ] Unauthenticated users are redirected to login

Do NOT write implementation steps like:

• Install passport.js
• Create auth middleware
• Add login route

Ask: "Does this capture what success looks like?"

5. Build Flow Graph

Compose flow based on detected stack. Pattern: developer -> reviewer -> stpa-analyst

Go backend:

flow: |
  "backend-go-developer" -> "go-readability-reviewer"
  "go-readability-reviewer" -> "stpa-analyst"

React frontend:

flow: |
  "react-developer" -> "react-reviewer"
  "react-reviewer" -> "stpa-analyst"

HTMX frontend:

flow: |
  "htmx-picocss-frontend-developer" -> "htmx-picocss-frontend-reviewer"
  "htmx-picocss-frontend-reviewer" -> "stpa-analyst"

Go + React (full stack):

flow: |
  "backend-go-developer" -> "go-readability-reviewer"
  "go-readability-reviewer" -> "stpa-analyst"
  "react-developer" -> "react-reviewer"
  "react-reviewer" -> "stpa-analyst"

Shell/CLI tools:

flow: |
  "shell-script-coder" -> "shell-script-reviewer"
  "shell-script-reviewer" -> "stpa-analyst"

Python/general with shell:

flow: |
  "general-purpose" -> "stpa-analyst"
  "shell-script-coder" -> "shell-script-reviewer"
  "shell-script-reviewer" -> "stpa-analyst"

Architecture documentation:

flow: |
  "c4-code" -> "c4-component"
  "c4-component" -> "c4-container"
  "c4-container" -> "c4-context"

General (no stack detected):

flow: |
  "general-purpose" -> "stpa-analyst"

Always include stpa-analyst as terminal node for safety analysis (except pure documentation flows).

6. Detect Completion Gate

Look for test commands:

7. Show Preview

Display the complete GOAL.md and ask:

"Here's the goal file. Ready to write it?"

8. Backup and Write

If GOAL.md exists:

1. Rename to GOAL.md.YYYY-MM-DD-HHMMSS.bak
2. Inform user of backup

Write new GOAL.md to repository root.

GOAL.md Format

---
flow: |
  "agent-a" -> "agent-b"
  "agent-b" -> "stpa-analyst"
models:
  "coordinator": "anthropic/claude-opus-4-6 (max)"
  "agent-a": "anthropic/claude-opus-4-6"
  "agent-b": "anthropic/claude-opus-4-6"
  "stpa-analyst": "anthropic/claude-opus-4-6"
interactive: yes
completionGateScript: go test ./...
---

Brief description of the goal in 1-2 sentences.

## Success Criteria

- [ ] Outcome-based criterion 1
- [ ] Outcome-based criterion 2
- [ ] Outcome-based criterion 3

Available Agents

Development Agents

Review Agents

Verification Agents

Deployment Agents

Documentation Agents (C4 Model)

Meta Agents

File References

To include context like screenshots or specs, add files to the repo and reference them:

See `docs/mockup.png` for the desired layout.
Refer to `specs/api.md` for endpoint requirements.

Decisions Made by This Skill

• Interactive mode: Always yes (agents ask clarifying questions)
• stpa-analyst: Always included as terminal reviewer
• Preferences location: .sgai/preferences.json in project
• Backup naming: GOAL.md.YYYY-MM-DD-HHMMSS.bak
• Success criteria style: Outcome-based, not implementation steps