# Humand Product Workflow

Shared Cursor skills and agent configuration for the Humand development team.

## Structure

```
config/
  repos.json
  sprint-report-context.json
  teams.json
scripts/
  fetch-jira-dev-info.sh
  fetch-jira-sprint-issues.sh
  generate-sprint-report.py
  process-sprint-data.py
  run-sprint-report.py
  search-prs-for-keys.sh
skills/
  feature-estimate-plan/
    SKILL.md
  pm-product-advisor/
    SKILL.md
    references/
    templates/
  hu-team-staging-status/
    SKILL.md
    team-staging-status.py
  setup/
    SKILL.md
  sprint-report/
    SKILL.md
```

## Setup

### Local (developers)

1. Install and authenticate the [GitHub CLI](https://cli.github.com/): `gh auth login`
2. Set Jira API credentials: `export JIRA_EMAIL=you@humand.com` and `export JIRA_API_TOKEN=<token>` (get token from https://id.atlassian.com/manage-profile/security/api-tokens)
3. (Optional) Configure the Atlassian MCP server in Cursor (fallback for Jira, required for Confluence)
4. Configure the Notion MCP server in Cursor (`https://mcp.notion.com/mcp`) — skills publish output to Notion pages
5. Run `/setup` in a conversation to verify everything works

### Cloud Agents (product managers)

1. Open https://cursor.com/dashboard?tab=cloud-agents and go to **My Settings**.
2. Add secret `GH_TOKEN` (read-only):
   - In GitHub: **Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens -> Generate new token**.
   - Minimum permissions: **Metadata: Read**, **Contents: Read**, **Pull requests: Read**, **Issues: Read**.
3. Add secret `JIRA_API_TOKEN` (read-only):
   - In Atlassian: **Account settings -> Security -> API tokens -> Create API token**.
   - Use an account with Jira browse/read permissions only.
4. Use Cloud Agents to run the skills:
   - Cursor Agents UI: https://cursor.com/agents
   - Slack: tag `@Cursor` with your request.

## Skills

| Skill | Purpose | Run |
|------|---------|-----|
| `/setup` | First-time setup wizard — verifies `gh`, Atlassian MCP, Notion MCP, repo access, and teams config | `/setup` |
| `/sprint-report <team>` | Cross-repo sprint health → Notion page: Jira tickets + linked PRs, status, blockers | `/sprint-report rhino` |
| `/feature-estimate-plan` | Evidence-backed per-repo effort assessment, feasibility, and execution plan → Notion page (output in Spanish) | Ask the agent to plan a feature |
| `/hu-team-staging-status` | Per-repo staging vs develop status → Notion page (Jira-first) | `/hu-team-staging-status shark` |
| `/humand-features-notion` | Document a Humand feature in the "Humand Features" Notion database (ES/EN, Sales + CX audience) | Ask the agent to document a feature |
| `/humand-pm-jira` | Jira CLI for PMs (search/get/create issues) + workflow to turn a Notion doc, Granola meeting, or pasted spec into proposed Jira cards | Ask the agent to create cards from a doc / meeting |
| `/pm-product-advisor` | Product Advisor: discovery iterativo (Notion, Figma, FigJam, Granola), edge cases y métricas Amplitude; síntesis a Jira (Design, Epic, Stories, card de métricas) usando **humand-pm-jira** | Ask for Product Advisor / "pensar esta feature" antes de crear cards |

## Reusable Scripts

Scripts in `scripts/` are shared across skills.

| Script | Purpose |
|--------|---------|
| `fetch-jira-sprint-issues.sh` | Fetch sprint issues via Jira REST API with automatic pagination |
| `fetch-jira-dev-info.sh` | Query Jira's dev-status REST API for linked PRs/branches per ticket |
| `process-sprint-data.py` | Merges MCP JSON pages, performs parent/subtask rollup, outputs compact digest + processed tickets JSON |
| `generate-sprint-report.py` | Takes Jira tickets JSON + optional PR data, categorizes tickets, outputs formatted markdown |
| `run-sprint-report.py` | End-to-end wrapper: resolves team, fetches Jira, searches PRs, generates report |
| `search-prs-for-keys.sh` | Batch-search PRs across all 6 repos for a set of Jira ticket keys |
