Pack Manager

{
  "id": "<pack_id>",
  "name": "Display Name",
  "description": "What this pack covers.",
  "version": "1.0.0",
  "author": "Arcana",
  "tags": ["tag1", "tag2"]
}

achievements.json

{
  "version": 1,
  "achievements": [
    {
      "id": "<pack_id>::<snake_case_name>",
      "name": "Fun Gamified Name",
      "description": "Clear explanation of what this achievement represents.",
      "difficulty": "beginner|intermediate|advanced|expert|legendary",
      "tags": ["meaningful-tag-1", "meaningful-tag-2"],
      "prerequisites": ["<pack_id>::<other_achievement>"]
    }
  ]
}

skills.json

{
  "version": 1,
  "skills": [
    {
      "id": "<pack_id>::<skill_name>",
      "name": "Skill Display Name",
      "description": "What proficiency in this skill means.",
      "max_level": 5,
      "level_thresholds": [
        { "level": 2, "points_required": 25 },
        { "level": 3, "points_required": 50, "required_key_achievements": ["<pack_id>::<key_ach>"] },
        { "level": 4, "points_required": 80 },
        { "level": 5, "points_required": 120, "required_key_achievements": ["<pack_id>::<key_ach>"] }
      ],
      "nodes": [
        {
          "node_id": "node_<short_name>",
          "achievement_id": "<pack_id>::<achievement>",
          "points": 10
        }
      ]
    }
  ]
}

Hard Rules (Schema Validation)

These rules are enforced by the Rust backend. Violating them causes load failure.

1. ID prefix: All achievement IDs MUST start with <pack_id>::. All skill IDs MUST start with <pack_id>::.
2. ID uniqueness: No duplicate achievement IDs within a pack. No duplicate node_ids within a skill.
3. Difficulty enum: Must be exactly one of: beginner, intermediate, advanced, expert, legendary.
4. Prerequisites DAG: prerequisites can only reference achievements within the same pack. The prerequisite graph must be acyclic (DAG).
5. Level thresholds count: level_thresholds array length MUST equal max_level - 1. Lv.1 is implicit (points >= 1 grants Lv.1 automatically) and MUST NOT appear in the array.
6. Points monotonically increasing: Each level's points_required must be strictly greater than the previous level's.
7. Key achievements valid: Every ID in required_key_achievements must be a valid achievement ID in the same pack.
8. Node achievement valid: Every nodes[].achievement_id must reference a valid achievement in the same pack.
9. required_key_achievements is incremental: Each level only lists NEW key achievements for that level. The algorithm auto-inherits from lower levels.

Quality Standards

These are not enforced by code but are critical for a good user experience.

Achievement Names — MUST be gamified and fun

• GOOD: "Inception" (for learning recursion), "Ship It!" (for completing a side project), "The Merge Master" (for first PR merged)
• BAD: "Use recursion", "Complete a side project", "First Pull Request Merged"
• Names should feel like real game achievements — memorable, sometimes witty, sometimes epic

Achievement Descriptions — MUST be informative and distinct from name

• The description explains WHAT the achievement actually is
• NEVER copy the name as the description
• Include enough detail that the user knows exactly what qualifies
• GOOD: name="Inception", description="Write a recursive function that calls itself to solve a problem, such as computing factorials or traversing a tree."
• BAD: name="Use recursion", description="Use recursion"

Difficulty Calibration

Difficulty reflects how far along a practitioner's journey this milestone typically occurs:

• beginner: Anyone starting out would do this in their first weeks/months
• intermediate: Requires some experience, typically months of practice
• advanced: Requires significant experience, typically 1-2+ years
• expert: Requires deep expertise, typically 3-5+ years or notable accomplishment
• legendary: Rare accomplishments that most practitioners never achieve

Think carefully: "Use a keyboard shortcut" is beginner, not expert. "Write a TCP/IP server" is advanced, not legendary. "Contribute to a major open-source project" is expert.

Tags — MUST be meaningful and differentiated

• Tags should be actually useful for filtering, not one-tag-fits-all
• No hard limit on tag count — use as many as genuinely apply
• Tags should create meaningful subgroups within the pack
• BAD: Every achievement tagged "programming" — this is useless as a filter
• GOOD: "algorithms", "web-dev", "systems", "collaboration", "devops", "data-structures"

Skills — MUST feel like real skills

• GOOD skill names: "Python", "Web Development", "Systems Programming", "Machine Learning", "DevOps"
• BAD skill names: "Fundamentals", "Tooling", "Community", "Advanced Topics"
• Each skill should have 20-80 nodes (achievement references)
• A pack should have multiple skills (not just one giant skill)

Points Calibration

• Points reflect the achievement's significance WITHIN that specific skill
• Difficulty levels should have meaningful point gaps to reflect the real effort difference:
  • beginner achievements: 5-10 points
  • intermediate: 10-25 points
  • advanced: 20-45 points
  • expert: 40-70 points
  • legendary: 60-100 points
• These are guidelines — adjust based on actual importance to the skill, but maintain significant gaps between tiers

Level Thresholds

• Typically use max_level 5
• Lv.1 is implicit: any points > 0 automatically grants Lv.1. Do NOT include a Lv.1 entry in level_thresholds.
• level_thresholds only contains entries for Lv.2 through Lv.max_level (so max_level - 1 entries).
• Points curve should be achievable but progressive (not linear — exponential-ish)
• Critical design principle: Reaching max level should NOT require unlocking every achievement in the skill. A skill may have many relevant achievements, but a practitioner doesn't need to complete all of them to be considered max level. Think of it as: there are many possible paths to mastery.
• When setting a level's points_required, mentally check: "What combination of achievements would add up to this threshold? Does completing those feel right for this level — not too easy, not too demanding?"
  • Example: If level 3 requires 100 points, imagine a concrete set of achievements totaling ~100. Would someone who completed exactly those achievements feel like a level 3? If it feels too high or too low, adjust.
• Total points available across all nodes should be significantly MORE than the max level threshold, giving users multiple paths to level up. There is no fixed ratio — it depends on the domain. A skill with many legendary achievements might have 4x+ the max threshold in total points, because those achievements are so hard that most people will only ever complete a few of them — but completing even one or two already demonstrates mastery. Design for reality, not for a formula.
• required_key_achievements: Only add when "if you haven't done X but claim level Y, it would seem ridiculous". Don't add them just for the sake of having them.

Same Achievement in Multiple Skills

• An achievement CAN appear in multiple skill trees with different point values
• Example: "Deploy a Docker container" could appear in both "DevOps" (15 pts) and "Web Development" (10 pts)

Workflow

Create Mode

1. Ask the user to describe the domain/topic for the pack
2. Propose a pack_id, name, and list of 3-7 skills with brief descriptions
3. Wait for user confirmation/adjustment
4. For each skill, generate the full achievement list with all fields
5. Present a summary (total achievements, per-skill node count, difficulty distribution)
6. Write all three JSON files to data/packs/<pack_id>/

Refine Mode

1. Read the existing pack files from data/packs/<pack_id>/
2. Analyze and report quality issues (bad names, duplicate descriptions, wrong difficulty, useless tags, poor skill organization)
3. Propose specific changes, grouped by category
4. Wait for user confirmation
5. Apply changes, preserving all existing achievement IDs (critical — progress data depends on stable IDs)
6. Write updated files

Extend Mode

1. Read the existing pack files from data/packs/<pack_id>/
2. Understand what already exists (skills, achievements, tags, difficulty distribution)
3. Propose new achievements and optionally new skills for the requested topic
4. New achievements CAN have prerequisites pointing to existing achievements
5. MUST NOT modify existing achievements (their IDs, names, descriptions, etc.)
6. Wait for user confirmation
7. Merge new content into existing files and write

Important Constraints

• Preserve existing IDs in Refine/Extend: The file data/achievement_progress.json tracks user progress by achievement ID. Changing an existing ID would orphan progress data. In Refine mode, you may change name/description/difficulty/tags but NEVER the id field. In Extend mode, only add new achievements.
• JSON validity: Output must be valid JSON. Always verify mentally before writing.
• No cross-pack references: Prerequisites can only reference achievements within the same pack. Skills can only reference achievements within the same pack.
• Incremental key achievements: When designing level_thresholds, remember that required_key_achievements is incremental — only list NEW requirements at each level.

Self-Check Before Writing

Before writing any file, verify:

• All achievement IDs follow <pack_id>::<name> format
• No duplicate achievement IDs
• All prerequisites reference valid achievement IDs within the same pack
• No cycles in prerequisite graph
• Difficulty values are valid enum values
• All skill IDs follow <pack_id>::<name> format
• level_thresholds count == max_level - 1 for each skill (Lv.1 is implicit, not in JSON)
• level_thresholds entries start from level 2 (no level 1 entry)
• points_required is monotonically increasing for each skill
• All node achievement_ids reference valid achievements
• No duplicate node_ids within a skill
• All required_key_achievements reference valid achievement IDs
• Names are gamified and fun (not boring literal descriptions)
• Descriptions are informative (not copies of names)
• Difficulty is calibrated realistically
• Tags are meaningful and differentiated
• Each skill has 20-80 nodes
• In Refine/Extend mode: no existing achievement IDs were changed