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

0. Verify SGAI Is in Use

Check for an .sgai/ directory or other SGAI configuration in the repository. If absent, stop and ask the user whether this repo actually uses SGAI before proceeding.

1. Detect Tech Stack

Scan the repository for files and choose appropriate agents:

Multiple stacks combine (e.g., Go + React = both agent chains). See agents-reference.md for the full agent catalog and additional flow-graph variants.

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. Core pattern: developer -> reviewer -> stpa-analyst

Go + React (full stack) example:

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

More flow variants (single-stack, shell/CLI, architecture documentation, general) are in agents-reference.md.

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

6. Detect Completion Gate

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

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.

Common Mistakes

• Implementation steps as success criteria — criteria must describe outcomes ("users can sign in"), not tasks ("add login route")
• Omitting stpa-analyst — always include it as the terminal reviewer, except in pure documentation flows
• Overwriting an existing GOAL.md without backup — always rename the old file to GOAL.md.YYYY-MM-DD-HHMMSS.bak first

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