# Muggles

**Repository Path**: sinall/muggles

## Basic Information

- **Project Name**: Muggles
- **Description**: 专为固定价格 (Fixed Price) 外包打造的 AI Agent 技能库。拒绝不可控的“魔法”，只做严守合同范围、确保确定性交付的务实工匠。

- **Primary Language**: Shell
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Muggles · 麻瓜

English | [中文](README.md)

**Muggles** (麻瓜) — An AI Agent skill library purpose-built for Fixed Price (FP) outsourcing projects. Works with [OpenCode](https://opencode.ai) to automate requirement estimation, management report generation, document writing, and more — in one sentence.

## Why Muggles?

FP outsourcing involves mountains of repetitive document work: estimating workloads, generating management reports, writing design docs, creating test cases... These tasks follow fixed templates, yet doing them manually is time-consuming and error-prone.

Muggles packages these repetitive tasks into **reusable AI skills**. Each skill is deterministic — same input, same output, every time. No more, no less, exactly as the contract promises.

## Skill Matrix

Skills are organized by project delivery phases:

| Phase | Skill | Description | Status |
|-------|-------|-------------|--------|
| Requirements | [workload-estimation](./skills/workload-estimation/SKILL.md) | Process requirement Excel, auto-calculate size, man-days, man-months | ✅ Done |
| Management | [project-management-excel](./skills/project-management-excel/SKILL.md) | Generate project management Excel from requirement list (template-based) | ✅ Done |
| Design | [module-design](./skills/module-design/SKILL.md) | Module design document generation (template-based) | ✅ Done |
| Testing | test-design | Test design (mind maps) | 📋 Planned |
| Testing | test-case-generator | Test case generation | 📋 Planned |
| Testing | test-report | Test report generation | 📋 Planned |
| Delivery | acceptance-document | Acceptance document generation | 📋 Planned |

## Typical Workflow

Here's how Muggles helps with an FP project:

1. **Receive requirement list Excel** → Use `workload-estimation` to auto-calculate size, man-days, man-months with live Excel formulas
2. **Need a management report** → Use `project-management-excel` to auto-generate a management table from a template, batch-filling requirement data
3. **More to come** → Module design, interface design, test cases, acceptance docs... progressively covering the entire delivery pipeline

## Installation

### Prerequisites

- [OpenCode](https://opencode.ai) installed
- Git installed

### Quick Install

Tell OpenCode:

```
Fetch and follow instructions from https://gitee.com/sinall/muggles/raw/master/.opencode/INSTALL.md
```

### Manual Install

```bash
# 1. Clone the repository
mkdir -p ~/.config/opencode/muggles
git clone https://gitee.com/sinall/muggles.git ~/.config/opencode/muggles

# 2. Register the plugin
mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/muggles/.opencode/plugin/muggles.js ~/.config/opencode/plugin/muggles.js

# 3. Restart OpenCode

# 4. Verify (run find_muggles_skills in OpenCode, should see skill list)
```

For detailed instructions, see [.opencode/INSTALL.md](.opencode/INSTALL.md).

## Usage

After installation, simply talk to OpenCode — the AI will automatically match relevant skills:

```
"Help me estimate workload for this FP project Excel file"
```

Or call manually:

- **`find_muggles_skills`** — List all available skills
- **`use_muggles_skill`** — Load a specific skill (parameter: `skill_name`)

### Version Pinning & Updates

```bash
# Pin to a specific version
git clone --branch v1.0.0 https://gitee.com/sinall/muggles.git ~/.config/opencode/muggles

# Update to latest
cd ~/.config/opencode/muggles && git pull
```

## Development Guide

See [AGENTS.md](AGENTS.md) for full details. Quick overview:

1. Create a directory under `skills/`, write a `SKILL.md`
2. Test the skill (with verification checklist)
3. Submit a Pull Request

## Documentation

- [AGENTS.md](AGENTS.md) — AI Agent development guide (skill template, code standards, testing)
- [Project Overview](docs/project-overview.md) — Skill system, development principles
- [Template System](docs/template-system.md) — Multi-level template architecture
- [Collaboration Guide](docs/collaboration-guide.md) — Git workflow, PR process
- [Skill Development](docs/skill-development.md) — Development workflow and standards
- [Testing Guide](docs/testing-guide.md) — How to test skills locally
- [Template Usage](templates/README.md) — Template lookup and placeholders
- [Changelog](CHANGELOG.md) — Version history

## Resources

- [OpenCode Docs](https://opencode.ai/docs/) — Platform documentation
- [Superpowers Framework](https://github.com/obra/superpowers) — Development methodology

## License

MIT License — See [LICENSE](LICENSE) file

---

*Muggles — No magic, just确定性 (determinism).*