Skip to content

aiskillstore/marketplace / skills/01000001-01001110/jira-safe

jira-safe

Verified

Implement SAFe methodology in Jira. Use when creating Epics, Features, Stories with proper hierarchy, acceptance criteria, and parent-child linking.

FileKindSize
SKILL.mdskill md13.5 KB
scripts/add-subtasks.mjsscript6.9 KB
scripts/add-subtasks.pyscript6.8 KB
scripts/create-mvp.mjsscript33.0 KB
scripts/create-mvp.pyscript38.3 KB
scripts/create-two-level.mjsscript22.5 KB
scripts/create-two-level.pyscript12.3 KB
skill-report.jsonconfig403.3 KB

scripts/create-two-level.mjs

View on GitHub
// Create Two-Level Hierarchy Epics and Stories
// Following jira-safe skill patterns for Next-Gen project
// Source: docs/epics/EPIC-001, EPIC-002, EPIC-003

// Load from environment variables (set by run.js or manually)
const JIRA_EMAIL = process.env.JIRA_EMAIL;
const JIRA_API_TOKEN = process.env.JIRA_API_TOKEN;
const JIRA_BASE_URL = process.env.JIRA_BASE_URL;
const PROJECT_KEY = process.env.JIRA_PROJECT_KEY || 'SCRUM';

// Validate required env vars
if (!JIRA_EMAIL || !JIRA_API_TOKEN || !JIRA_BASE_URL) {
  console.error('Error: Missing required environment variables.');
  console.error('Required: JIRA_EMAIL, JIRA_API_TOKEN, JIRA_BASE_URL');
  console.error('Set these in .claude/skills/jira/.env or export them manually.');
  process.exit(1);
}

const auth = Buffer.from(`${JIRA_EMAIL}:${JIRA_API_TOKEN}`).toString('base64');
const headers = {
  'Authorization': `Basic ${auth}`,
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

// ==================== SKILL PATTERNS ====================
// From .claude/skills/jira/jira-safe/SKILL.md

// ADF Helper (Atlassian Document Format)
function buildADF(content) {
  return { type: 'doc', version: 1, content };
}

function heading(level, text) {
  return {
    type: 'heading',
    attrs: { level },
    content: [{ type: 'text', text }]
  };
}

function paragraph(text) {
  return {
    type: 'paragraph',
    content: [{ type: 'text', text }]
  };
}

function bulletList(items) {
  return {
    type: 'bulletList',
    content: items.map(item => ({
      type: 'listItem',
      content: [{ type: 'paragraph', content: [{ type: 'text', text: item }] }]
    }))
  };
}

// Create Issue (from skill pattern)
async function createIssue(fields) {
  const response = await fetch(`${JIRA_BASE_URL}/rest/api/3/issue`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ fields })
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`${response.status}: ${error.substring(0, 200)}`);
  }

  return response.json();
}

function delay(ms) {
  return new Promise(r => setTimeout(r, ms));
}

// ==================== EPIC & STORY DEFINITIONS ====================
// From docs/epics/EPIC-001-database-migration.md, EPIC-002-backend-api.md, EPIC-003-frontend-ui.md

const epics = [
  {
    id: 'EPIC-001',
    summary: 'EPIC-001: Database Migration - Two-Level Hierarchy',
    description: buildADF([
      heading(2, 'Business Outcome'),
      paragraph('Transform the current single-level database structure (users → brands) into a two-level hierarchy (users → clients → brands) to support agencies managing multiple client companies.'),
      heading(2, 'Success Criteria'),
      bulletList([
        'clients table created with proper schema',
        'brands.clientId column added and populated',
        '100% of existing brands mapped to clients',
        'All foreign key constraints enforced',
        'Zero data loss during migration'
      ]),
      heading(2, 'Dependencies'),
      paragraph('None - this is the foundational epic')
    ]),
    labels: ['two-level-hierarchy', 'database'],
    stories: [
      {
        id: 'US-001.1',
        summary: 'US-001.1: As a database administrator, I want to create a clients table, so that users can manage multiple client companies',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a database administrator, I want to create a new clients table with proper schema, indexes, and constraints, so that users can manage multiple client companies, each with their own brands.'),
          heading(2, 'Acceptance Criteria'),
          heading(3, 'Scenario: Table Creation'),
          bulletList([
            'GIVEN the database schema needs updating',
            'WHEN the migration runs',
            'THEN clients table exists with id, user_id, name, is_default, created_at, updated_at'
          ]),
          heading(2, 'Definition of Done'),
          bulletList([
            '[ ] Migration file created and tested',
            '[ ] Rollback SQL documented',
            '[ ] TypeScript types auto-generated',
            '[ ] PR merged to master'
          ])
        ]),
        labels: ['database', 'epic-001'],
        subtasks: [
          'Define clients table schema in Drizzle ORM',
          'Add user_id foreign key with CASCADE delete',
          'Create index on user_id for performance',
          'Add unique partial index for default client per user',
          'Generate migration file',
          'Create validation queries',
          'Test on Neon branch'
        ]
      },
      {
        id: 'US-001.2',
        summary: 'US-001.2: As a database administrator, I want to add clientId column to brands, so that brands are associated with clients',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a database administrator, I want to add a nullable client_id foreign key column to the brands table, so that each brand can be associated with a client company.'),
          heading(2, 'Acceptance Criteria'),
          bulletList([
            'GIVEN the brands table exists',
            'WHEN the migration runs',
            'THEN client_id column is added as nullable UUID'
          ]),
          heading(2, 'Definition of Done'),
          bulletList([
            '[ ] Column added as NULLABLE',
            '[ ] Index created on client_id',
            '[ ] FK references clients.id with CASCADE',
            '[ ] PR merged to master'
          ])
        ]),
        labels: ['database', 'epic-001'],
        subtasks: [
          'Add clientId field to brands schema',
          'Configure as nullable UUID',
          'Add foreign key reference to clients.id',
          'Set onDelete: cascade',
          'Create index on client_id',
          'Generate migration file',
          'Test on Neon branch'
        ]
      },
      {
        id: 'US-001.3',
        summary: 'US-001.3: As a database administrator, I want to migrate existing brands to clients, so that all data follows two-level hierarchy',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a database administrator, I want to create a client for each existing brand and link them, so that existing data is migrated to the new two-level hierarchy.'),
          heading(2, 'Acceptance Criteria'),
          bulletList([
            'GIVEN existing brands without clients',
            'WHEN migration runs',
            'THEN one client created per brand with matching user_id',
            'AND each brand.client_id points to its new client'
          ])
        ]),
        labels: ['database', 'epic-001'],
        subtasks: [
          'Create data migration script',
          'For each brand, create client with same user_id',
          'Update brand.client_id to new client.id',
          'Verify 0 brands with NULL client_id',
          'Verify brand_count = client_count'
        ]
      },
      {
        id: 'US-001.4',
        summary: 'US-001.4: As a database administrator, I want to enforce NOT NULL on clientId, so that data integrity is guaranteed',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a database administrator, I want to make client_id NOT NULL and add final constraints, so that data integrity is enforced at the database level.'),
          heading(2, 'Acceptance Criteria'),
          bulletList([
            'GIVEN all brands have client_id populated',
            'WHEN constraint added',
            'THEN client_id column is NOT NULL'
          ])
        ]),
        labels: ['database', 'epic-001'],
        subtasks: [
          'Verify 0 NULL client_id values',
          'Alter column to NOT NULL',
          'Add unique partial index for default brand per client',
          'Update drizzle schema',
          'Generate final migration'
        ]
      }
    ]
  },
  {
    id: 'EPIC-002',
    summary: 'EPIC-002: Backend API - Two-Level Hierarchy',
    description: buildADF([
      heading(2, 'Business Outcome'),
      paragraph('Implement comprehensive backend API support for the two-level hierarchy including client CRUD, updated brand APIs, limit enforcement, and ownership verification.'),
      heading(2, 'Success Criteria'),
      bulletList([
        'Client CRUD endpoints implemented (/api/clients/*)',
        'Brand API requires clientId parameter',
        'Two-level limit enforcement working',
        'All DELETE/PUT have ownership checks'
      ]),
      heading(2, 'Dependencies'),
      paragraph('EPIC-001 (Database Migration) must be complete')
    ]),
    labels: ['two-level-hierarchy', 'api'],
    stories: [
      {
        id: 'US-002.1',
        summary: 'US-002.1: As a frontend developer, I want client CRUD API endpoints, so that users can manage client companies',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a frontend developer, I want complete CRUD API endpoints for client management, so that users can create, read, update, and delete their client companies.'),
          heading(2, 'Endpoints'),
          bulletList([
            'GET /api/clients - List all clients',
            'POST /api/clients - Create with limit check',
            'GET /api/clients/[id] - Get single client',
            'PUT /api/clients/[id] - Update with ownership check',
            'DELETE /api/clients/[id] - Delete with cascade'
          ])
        ]),
        labels: ['api', 'epic-002'],
        subtasks: [
          'Create app/api/clients/route.ts (GET, POST)',
          'Implement GET - list clients for user',
          'Implement POST - create with limit check',
          'Create app/api/clients/[id]/route.ts',
          'Implement ownership verification helper',
          'Add Zod validation schemas',
          'Create unit tests'
        ]
      },
      {
        id: 'US-002.2',
        summary: 'US-002.2: As a frontend developer, I want brand API updated for client hierarchy, so that brands are scoped to clients',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a frontend developer, I want brand API updated to require clientId parameter, so that brands are properly scoped to client companies.'),
          heading(2, 'Changes'),
          bulletList([
            'POST /api/brands requires clientId',
            'GET /api/clients/[id]/brands returns brands for client',
            'PUT/DELETE have ownership verification'
          ])
        ]),
        labels: ['api', 'epic-002'],
        subtasks: [
          'Update POST /api/brands to require clientId',
          'Create GET /api/clients/[id]/brands endpoint',
          'Add ownership verification to DELETE',
          'Add ownership verification to PUT',
          'Add tests for cross-client access prevention'
        ]
      },
      {
        id: 'US-002.3',
        summary: 'US-002.3: As a billing system, I want two-level limit enforcement, so that subscription tiers are enforced',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a billing system, I want two-level limit enforcement, so that users cannot exceed their client or brand limits.'),
          heading(2, 'Limits by Tier'),
          bulletList([
            'Trial: 1 client, 2 brands per client',
            'Pro: 10 clients, 10 brands per client',
            'Unlimited: No limits'
          ])
        ]),
        labels: ['api', 'epic-002'],
        subtasks: [
          'Create lib/subscription/limits.ts',
          'Define limit constants by tier',
          'Implement getClientCount(userId)',
          'Implement getBrandCount(clientId)',
          'Add atomic limit checks'
        ]
      },
      {
        id: 'US-002.4',
        summary: 'US-002.4: As a security system, I want two-level ownership verification, so that users can only access their data',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a security system, I want two-level ownership verification on all endpoints, so that users cannot access other users data.'),
          heading(2, 'Requirements'),
          bulletList([
            'verifyClientOwnership(userId, clientId) helper',
            'verifyBrandOwnership(userId, brandId) helper',
            'Applied to all client and brand endpoints'
          ])
        ]),
        labels: ['api', 'security', 'epic-002'],
        subtasks: [
          'Create lib/auth/ownership.ts',
          'Implement verifyClientOwnership',
          'Implement verifyBrandOwnership',
          'Apply to all endpoints',
          'Create security test suite'
        ]
      },
      {
        id: 'US-002.5',
        summary: 'US-002.5: As an AI system, I want context builder updated, so that client info is included in AI prompts',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As an AI system, I want brand context builder to include client information, so that AI responses are aware of the client company context.')
        ]),
        labels: ['api', 'ai', 'epic-002'],
        subtasks: [
          'Update lib/ai/context-builder.ts',
          'Add client name to context',
          'Test context generation',
          'Verify backward compatibility'
        ]
      }
    ]
  },
  {
    id: 'EPIC-003',
    summary: 'EPIC-003: Frontend UI - Two-Level Hierarchy',
    description: buildADF([
      heading(2, 'Business Outcome'),
      paragraph('Implement complete frontend UI support for the two-level hierarchy including client management pages, two-level selector, updated onboarding, and subscription limit displays.'),
      heading(2, 'Success Criteria'),
      bulletList([
        'Client management page at /dashboard/clients',
        'Two-level selector in dashboard header',
        'Onboarding Step 0 creates client',
        'Responsive design (mobile/tablet/desktop)'
      ]),
      heading(2, 'Dependencies'),
      paragraph('EPIC-002 (Backend API) must be complete')
    ]),
    labels: ['two-level-hierarchy', 'frontend'],
    stories: [
      {
        id: 'US-003.1',
        summary: 'US-003.1: As a user, I want a client management page, so that I can create and manage client companies',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a user, I want to manage my client companies from a dedicated page, so that I can create, view, edit, and delete clients easily.'),
          heading(2, 'Features'),
          bulletList([
            'Page at /dashboard/clients',
            'List all clients in card format',
            'Show brand count per client',
            'Create/Edit/Delete functionality'
          ])
        ]),
        labels: ['frontend', 'epic-003'],
        subtasks: [
          'Create app/dashboard/clients/page.tsx',
          'Add to dashboard navigation',
          'Implement client list component',
          'Create New Client modal',
          'Add delete confirmation dialog',
          'Handle loading/error/empty states'
        ]
      },
      {
        id: 'US-003.2',
        summary: 'US-003.2: As a user, I want a two-level selector, so that I can switch between clients and brands',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a user, I want to use a two-level selector to switch clients and brands, so that I can quickly navigate between different client companies.'),
          heading(2, 'Features'),
          bulletList([
            'Client dropdown (top level)',
            'Brand dropdown (filtered by client)',
            'Selection persists across navigation'
          ])
        ]),
        labels: ['frontend', 'epic-003'],
        subtasks: [
          'Create client-brand-selector.tsx',
          'Implement client dropdown',
          'Implement brand dropdown filtered by client',
          'Persist selection to localStorage',
          'Sync with URL params'
        ]
      },
      {
        id: 'US-003.3',
        summary: 'US-003.3: As a new user, I want onboarding to create a client first, so that brands are properly organized',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a new user, I want to create a client company during onboarding, so that my first brand is properly associated with a client.'),
          heading(2, 'Flow'),
          bulletList([
            'Step 0: What is your company name? (creates client)',
            'Steps 1-6: Existing brand questionnaire'
          ])
        ]),
        labels: ['frontend', 'epic-003'],
        subtasks: [
          'Add Step 0 to onboarding flow',
          'Create client name input form',
          'Call POST /api/clients on Step 0',
          'Pass clientId to brand creation'
        ]
      },
      {
        id: 'US-003.4',
        summary: 'US-003.4: As a user, I want a client profile page, so that I can view and edit client details',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a user, I want to view and edit client details on a dedicated page.')
        ]),
        labels: ['frontend', 'epic-003'],
        subtasks: [
          'Create app/dashboard/clients/[id]/page.tsx',
          'Display client details',
          'Add edit functionality',
          'Show brands list'
        ]
      },
      {
        id: 'US-003.5',
        summary: 'US-003.5: As a user, I want brand management scoped to client, so that brands are organized by client',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a user, I want to see brands filtered by selected client, so that I only see relevant brands.')
        ]),
        labels: ['frontend', 'epic-003'],
        subtasks: [
          'Update brands page to filter by client',
          'Pass clientId to brand creation',
          'Show default brand badge per client'
        ]
      },
      {
        id: 'US-003.6',
        summary: 'US-003.6: As a user, I want to see subscription limits, so that I know when to upgrade',
        description: buildADF([
          heading(2, 'User Story'),
          paragraph('As a user, I want to see my current usage vs subscription limits, so that I know when I am approaching limits.')
        ]),
        labels: ['frontend', 'epic-003'],
        subtasks: [
          'Create usage-display.tsx component',
          'Show client count vs limit',
          'Show brand count vs limit',
          'Add Upgrade prompt'
        ]
      }
    ]
  }
];

// ==================== MAIN ====================

async function main() {
  console.log('========================================');
  console.log('  CREATE TWO-LEVEL HIERARCHY BACKLOG');
  console.log('  Following jira-safe skill patterns');
  console.log('========================================\n');

  const results = {
    epics: { created: 0, failed: 0, keys: [] },
    stories: { created: 0, failed: 0, keys: [] },
    subtasks: { created: 0, failed: 0 }
  };

  for (const epic of epics) {
    console.log(`\n--- ${epic.id} ---`);

    // Create Epic (Next-Gen: no customfield_10011)
    try {
      const epicIssue = await createIssue({
        project: { key: PROJECT_KEY },
        issuetype: { name: 'Epic' },
        summary: epic.summary,
        description: epic.description,
        labels: epic.labels
      });
      console.log(`+ Epic: ${epicIssue.key}`);
      results.epics.created++;
      results.epics.keys.push({ key: epicIssue.key, id: epic.id });

      await delay(150);

      // Create Stories under Epic (Next-Gen: use parent field)
      for (const story of epic.stories) {
        try {
          const storyIssue = await createIssue({
            project: { key: PROJECT_KEY },
            issuetype: { name: 'Story' },
            summary: story.summary,
            description: story.description,
            parent: { key: epicIssue.key },  // Next-Gen pattern from skill
            labels: story.labels
          });
          console.log(`  + Story: ${storyIssue.key} (${story.id})`);
          results.stories.created++;
          results.stories.keys.push({ key: storyIssue.key, id: story.id, epicKey: epicIssue.key });

          await delay(100);

          // Create Subtasks (Next-Gen: use 'Subtask' not 'Sub-task')
          if (story.subtasks && story.subtasks.length > 0) {
            for (const subtaskSummary of story.subtasks) {
              try {
                const subtaskIssue = await createIssue({
                  project: { key: PROJECT_KEY },
                  issuetype: { name: 'Subtask' },  // Next-Gen pattern from skill
                  summary: subtaskSummary,
                  parent: { key: storyIssue.key }
                });
                console.log(`    + Subtask: ${subtaskIssue.key}`);
                results.subtasks.created++;
              } catch (err) {
                console.log(`    - FAILED: ${err.message.substring(0, 50)}`);
                results.subtasks.failed++;
              }
              await delay(50);
            }
          }

        } catch (err) {
          console.log(`  - FAILED ${story.id}: ${err.message.substring(0, 80)}`);
          results.stories.failed++;
        }
      }

    } catch (err) {
      console.log(`- FAILED ${epic.id}: ${err.message.substring(0, 80)}`);
      results.epics.failed++;
    }
  }

  console.log('\n========================================');
  console.log('  SUMMARY');
  console.log('========================================');
  console.log(`Epics:    ${results.epics.created} created, ${results.epics.failed} failed`);
  console.log(`Stories:  ${results.stories.created} created, ${results.stories.failed} failed`);
  console.log(`Subtasks: ${results.subtasks.created} created, ${results.subtasks.failed} failed`);

  console.log('\n--- Created Issues ---');
  for (const epic of results.epics.keys) {
    console.log(`${epic.key}: ${epic.id}`);
    for (const story of results.stories.keys.filter(s => s.epicKey === epic.key)) {
      console.log(`  └─ ${story.key}: ${story.id}`);
    }
  }

  console.log(`\n========================================`);
  console.log(`View: ${JIRA_BASE_URL}/jira/software/projects/${PROJECT_KEY}/boards/1/backlog`);
  console.log('========================================');
}

main().catch(console.error);
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall