construction-pm

人工智能代理的建设项目管理工具包。在以下情况下使用：(1) 跟踪施工作业从潜在客户到付费的整个生命周期，(2) 生成有关作业状态和管道运行状况的每日 PM 简报，(3) 检查过时的许可证或需要关注的老化作业，(4) 解析项目经理的电子邮件以获取作业更新，(5) 监控所有作业状态的收入管道。

# Construction PM

Production-tested construction project management toolkit. Built from real roofing company workflows managing 36+ active jobs and $1.8M+ pipeline.

## When to Activate

Use Construction PM when:
1. **Tracking jobs** through the full lifecycle (lead → estimate → sold → permitted → scheduled → in-progress → complete → invoiced → paid)
2. **Generating daily briefings** for project managers on job status and pipeline health
3. **Checking permits** - identifying permits pending longer than threshold days
4. **Parsing emails** from field staff for job status updates
5. **Monitoring pipeline revenue** across all job statuses to forecast cash flow

## Guardrails / Anti-Patterns

**DO:**
- ✓ Initialize the database with `init.sh` before using other commands
- ✓ Use consistent job numbers that match your accounting/CRM system
- ✓ Update job status promptly when conditions change
- ✓ Run daily briefings to catch stale jobs before they fall through cracks
- ✓ Set permit-check thresholds appropriate for your jurisdiction (14-30 days typical)

**DON'T:**
- ✗ Delete job history - status changes are append-only audit trail
- ✗ Skip the stale check - jobs without updates often indicate problems
- ✗ Use generic customer names - be specific for searchability
- ✗ Forget to set permit numbers when available - they're required for inspections
- ✗ Mix currency formats - use plain integers (49000 not $49,000 or 49k)

## Quick Start

```bash
# Initialize the job tracker (creates JSON database)
bash scripts/init.sh

# Or specify a custom data directory
DATA_DIR=/path/to/data bash scripts/init.sh
```

Default data location: `construction-pm-data/` in your workspace.

## Job Pipeline

### Add a job
```bash
bash scripts/add-job.sh \
  --number "12043" \
  --customer "Nichols" \
  --address "123 Main St" \
  --pm "Greg" \
  --value 49000 \
  --status "permitted" \
  --permit-status "approved" \
  --notes "Roof replacement, 30sq"
```

### Update job status
```bash
bash scripts/add-job.sh --number "12043" --status "in-progress" --notes "Crew on site Monday"
```

### View pipeline
```bash
# All jobs
bash scripts/pipeline.sh

# Filter by status
bash scripts/pipeline.sh --status permitted

# Filter by PM
bash scripts/pipeline.sh --pm Greg

# Stale jobs (no update in 14+ days)
bash scripts/pipeline.sh --stale 14

# Summary stats
bash scripts/pipeline.sh --summary
```

## Daily Briefing

```bash
# Generate today's briefing
bash scripts/briefing.sh

# Custom stale threshold
bash scripts/briefing.sh --stale-days 7

# Output to file
bash scripts/briefing.sh > /path/to/briefing.md
```

The briefing includes:
- Jobs starting this week
- Permits pending > 7 days
- Stale jobs (no update in 14+ days)
- Pipeline summary by status
- Revenue at each stage

## Permit Tracking

```bash
# Check all pending permits
bash scripts/permit-check.sh

# Flag permits older than N days
bash scripts/permit-check.sh --threshold 30
```

## Email Parsing

```bash
# Parse a PM email for job updates
bash scripts/parse-email.sh --file /path/to/email.txt

# Parse from stdin
echo "Job 12043 Nichols - permit approved, scheduling crew for next week" | bash scripts/parse-email.sh
```

Extracts: job numbers, customer names, status keywords, permit mentions, dates.

## Job Statuses

| Status | Description |
|--------|-------------|
| `lead` | Initial inquiry, not yet estimated |
| `estimate` | Estimate sent, waiting for approval |
| `sold` | Contract signed, not yet permitted |
| `permitted` | Permits approved, ready to schedule |
| `scheduled` | Crew and materials scheduled |
| `in-progress` | Work underway |
| `complete` | Work done, pending final inspection |
| `invoiced` | Invoice sent |
| `paid` | Payment received |
| `on-hold` | Paused for any reason |
| `cancelled` | Job cancelled |

## Data Format

Jobs are stored as JSON in `construction-pm-data/jobs.json`:

```json
{
  "jobs": [
    {
      "number": "12043",
      "customer": "Nichols",
      "address": "123 Main St",
      "pm": "Greg",
      "value": 49000,
      "status": "permitted",
      "permit_status": "approved",
      "permit_number": "",
      "notes": "Roof replacement, 30sq",
      "created": "2026-02-08",
      "updated": "2026-02-08",
      "history": [
        {"date": "2026-02-08", "from": "", "to": "permitted", "note": "Initial entry"}
      ]
    }
  ]
}
```

## Integration with OpenClaw

The briefing script outputs clean Markdown. Pipe it to your preferred delivery:
- Telegram: `bash scripts/briefing.sh | your-send-script`
- Obsidian vault: `bash scripts/briefing.sh > ~/vault/Inbox/PM-Briefing-$(date +%F).md`
- Email: Combine with `gog gmail send`

## Construction-Specific Features

- **Permit aging**: Flags permits pending longer than threshold
- **Revenue pipeline**: Shows total value at each stage
- **Stale detection**: Catches jobs that fell through the cracks
- **Status history**: Full audit trail of every status change
- **Trade-aware**: Understands roofing, siding, gutters, HVAC, electrical

---

## 中文说明

# Construction PM

经过生产环境验证的建筑项目管理工具包。基于真实的屋顶公司工作流构建，可管理 36 个以上的进行中作业及 180 万美元以上的管道。

## 何时启用

在以下情况下使用 Construction PM：
1. **跟踪作业**贯穿完整生命周期（lead → estimate → sold → permitted → scheduled → in-progress → complete → invoiced → paid）
2. **生成每日简报**，向项目经理汇报作业状态和管道运行状况
3. **检查许可证** —— 识别待审超过阈值天数的许可证
4. **解析邮件** —— 从一线员工的邮件中提取作业状态更新
5. **监控管道收入** —— 跨所有作业状态监控收入以预测现金流

## 护栏 / 反模式

**应该做：**
- ✓ 在使用其他命令前先用 `init.sh` 初始化数据库
- ✓ 使用与你的财务/CRM 系统一致的作业编号
- ✓ 状况变化时及时更新作业状态
- ✓ 运行每日简报，在陈旧作业被遗漏之前及时发现
- ✓ 设置适合你所在辖区的许可证检查阈值（通常为 14-30 天）

**不应该做：**
- ✗ 删除作业历史 —— 状态变更是仅追加的审计轨迹
- ✗ 跳过陈旧检查 —— 长期无更新的作业往往意味着存在问题
- ✗ 使用通用的客户名称 —— 应具体以便于搜索
- ✗ 忘记在有许可证编号时填写 —— 检查时需要用到
- ✗ 混用货币格式 —— 使用纯整数（49000，而非 $49,000 或 49k）

## 快速开始

```bash
# Initialize the job tracker (creates JSON database)
bash scripts/init.sh

# Or specify a custom data directory
DATA_DIR=/path/to/data bash scripts/init.sh
```

默认数据位置：工作区中的 `construction-pm-data/`。

## 作业管道

### 添加作业
```bash
bash scripts/add-job.sh \
  --number "12043" \
  --customer "Nichols" \
  --address "123 Main St" \
  --pm "Greg" \
  --value 49000 \
  --status "permitted" \
  --permit-status "approved" \
  --notes "Roof replacement, 30sq"
```

### 更新作业状态
```bash
bash scripts/add-job.sh --number "12043" --status "in-progress" --notes "Crew on site Monday"
```

### 查看管道
```bash
# All jobs
bash scripts/pipeline.sh

# Filter by status
bash scripts/pipeline.sh --status permitted

# Filter by PM
bash scripts/pipeline.sh --pm Greg

# Stale jobs (no update in 14+ days)
bash scripts/pipeline.sh --stale 14

# Summary stats
bash scripts/pipeline.sh --summary
```

## 每日简报

```bash
# Generate today's briefing
bash scripts/briefing.sh

# Custom stale threshold
bash scripts/briefing.sh --stale-days 7

# Output to file
bash scripts/briefing.sh > /path/to/briefing.md
```

简报包含：
- 本周开工的作业
- 待审超过 7 天的许可证
- 陈旧作业（14 天以上无更新）
- 按状态汇总的管道概览
- 各阶段的收入

## 许可证跟踪

```bash
# Check all pending permits
bash scripts/permit-check.sh

# Flag permits older than N days
bash scripts/permit-check.sh --threshold 30
```

## 邮件解析

```bash
# Parse a PM email for job updates
bash scripts/parse-email.sh --file /path/to/email.txt

# Parse from stdin
echo "Job 12043 Nichols - permit approved, scheduling crew for next week" | bash scripts/parse-email.sh
```

提取内容：作业编号、客户名称、状态关键词、许可证提及、日期。

## 作业状态

| 状态 | 说明 |
|--------|-------------|
| `lead` | 初次咨询，尚未估价 |
| `estimate` | 已发送估价，等待批准 |
| `sold` | 已签合同，尚未取得许可证 |
| `permitted` | 许可证已批准，可排期 |
| `scheduled` | 已安排施工队和材料 |
| `in-progress` | 施工进行中 |
| `complete` | 施工完成，待最终验收 |
| `invoiced` | 已开具发票 |
| `paid` | 已收款 |
| `on-hold` | 因任何原因暂停 |
| `cancelled` | 作业已取消 |

## 数据格式

作业以 JSON 形式存储于 `construction-pm-data/jobs.json`：

```json
{
  "jobs": [
    {
      "number": "12043",
      "customer": "Nichols",
      "address": "123 Main St",
      "pm": "Greg",
      "value": 49000,
      "status": "permitted",
      "permit_status": "approved",
      "permit_number": "",
      "notes": "Roof replacement, 30sq",
      "cre