niahere 0.2.58 → 0.2.60

package/README.md

@@ -1,5 +1,9 @@
 # nia
 
+[![npm version](https://img.shields.io/npm/v/niahere.svg)](https://www.npmjs.com/package/niahere)
+[![npm downloads](https://img.shields.io/npm/dm/niahere.svg)](https://www.npmjs.com/package/niahere)
+[![license](https://img.shields.io/npm/l/niahere.svg)](https://github.com/onlyoneaman/niahere/blob/main/LICENSE)
+
 A personal AI agent you fork and make your own. Small enough to understand, built for one user. Powered by Claude Agent SDK.
 
 - npm package: [`niahere`](https://www.npmjs.com/package/niahere)
@@ -33,7 +37,7 @@ nia start               # starts daemon + registers OS service
 - **Telegram** — message your agent from your phone, typing indicator while processing
 - **Slack** — Socket Mode bot with thread awareness, thinking emoji, watch channels for proactive monitoring
 - **Terminal chat** — REPL with session resume support
-- **Scheduled jobs** — recurring jobs and crons that run Claude and can message you back
+- **Scheduled jobs** — recurring jobs and crons that run Claude and can message you back. Stateful by default (working memory), per-job model routing for cost savings
 - **Persona system** — customizable identity, soul, owner profile, rules, and memory (preloaded every session)
 - **Agents** — domain specialists (marketer, senior-dev) via Claude Agent SDK subagents
 - **Skills** — loads skills from multiple directories, invokable as slash commands
@@ -63,8 +67,8 @@ nia update                     — update to latest version (auto-backup + resta
 nia job list                   — list all jobs
 nia job show [name]            — full details + recent runs
 nia job status [name]          — quick status check
-nia job add <n> <s> <p>        — add a job (--type, --always, --agent, --stateless, --prompt-file)
-nia job update <name>          — update a job (--schedule, --prompt, --prompt-file, --type, --always, --agent, --stateless)
+nia job add <n> <s> <p>        — add a job (--type, --always, --agent, --model, --stateless, --prompt-file)
+nia job update <name>          — update a job (--schedule, --prompt, --prompt-file, --type, --always, --agent, --model, --stateless)
 nia job remove <name>          — delete a job
 nia job enable / disable <n>   — toggle a job
 nia job run <name>             — run a job once
@@ -106,6 +110,8 @@ All config and data lives in `~/.niahere/`:
     soul.md         — how the agent works
     rules.md        — behavioral instructions (loaded every session)
     memory.md       — persistent facts and context (loaded every session)
+  jobs/               — per-job working memory and state (auto-created)
+  optimizations/      — optimization loop run workspaces
   images/
     reference.webp  — visual identity reference image
     profile.webp    — profile picture for Telegram/Slack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niahere",
-  "version": "0.2.58",
+  "version": "0.2.60",
   "description": "A personal AI assistant daemon — chat, scheduled jobs, persona system, extensible via skills.",
   "type": "module",
   "scripts": {
@@ -43,7 +43,7 @@
   "license": "MIT",
   "private": false,
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.74",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.97",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@slack/bolt": "^4.6.0",
     "cron-parser": "^5.5.0",

package/skills/agent-skill-creator/SKILL.md

@@ -1,149 +1,88 @@
 ---
 name: agent-skill-creator
-description: Create or improve reusable agent skills that are framework-agnostic and easy to maintain. Use when building a new skill or updating an existing one with clear triggers, workflows, reusable resources, and validation steps.
+description: "Create or improve AI agent skills with proper progressive disclosure, description optimization, and router patterns. Use when building a new skill, updating an existing one, merging related skills into a router, auditing skill quality, or improving skill activation rates. Also use when the user mentions 'create a skill,' 'write a skill,' 'new skill,' 'skill template,' 'improve this skill,' 'skill isn't triggering,' 'merge these skills,' or 'skill architecture.'"
+metadata:
+  version: 2.1.0
 ---
 
-## Agent Skill Creator
+# Skill Creator
 
-Create skills that any AI assistant can follow, not just one vendor or runtime.
+## Before Starting
 
-## Default Location
+1. **New or improving?** — Creating from scratch vs updating existing
+2. **Process or knowledge?** — Workflow steps → skill. Reference catalog → `references/` file, not a standalone skill.
+3. **Standalone or merge?** — Check if related skills exist that should become one router.
 
-New skills go in `~/.niahere/skills/<skill-name>/SKILL.md`. This directory is auto-scanned.
-When updating an existing skill, edit it in place wherever it lives.
+## Step 1: Write the Description
 
-## Goals
+The description determines activation. Most important thing you write.
 
-- Make the skill portable across tools and agent frameworks.
-- Keep instructions concise, explicit, and testable.
-- Prefer reusable artifacts (scripts, references, templates) over repeating long instructions.
+**Rules:**
+- Third person only
+- WHAT it does + WHEN to use it + 5+ trigger phrases
+- Negative boundaries (what it does NOT do)
+- Max 1024 characters
 
-## Workflow
-
-### 1. Clarify scope with concrete examples
-
-Collect 3-5 realistic user requests the skill should handle.
-
-For each example, define:
-- Input shape (files, links, text, constraints)
-- Expected output
-- Quality bar (correctness, formatting, speed, safety)
-
-### 2. Define trigger metadata
-
-Write metadata that helps an agent decide when to use this skill.
-
-- `name`: short, hyphenated, action-oriented
-- `description`: what it does + clear trigger contexts
-
-Write descriptions with explicit cues such as:
-- task types
-- file types
-- domains
-- decision boundaries (when not to use)
-
-### 3. Design the skill structure
-
-Pick the simplest structure that fits:
-
-- Workflow-based: ordered steps for sequential processes
-- Task-based: independent operations/tooling
-- Reference-based: policy/spec driven tasks
-- Hybrid: small workflow + task sections
-
-Keep core instructions in `SKILL.md`. Move large detail into references.
-
-### 4. Add reusable resources only when they pay off
-
-Use optional folders as needed:
-
-- `scripts/`: deterministic repeatable operations
-- `references/`: detailed docs, schemas, standards
-- `assets/`: templates, boilerplate, media, examples
-
-Rules:
-- Do not create empty folders by default.
-- Avoid duplicate content between `SKILL.md` and references.
-- Prefer one good script over long repeated prose.
-
-### 5. Write implementation instructions
-
-In `SKILL.md`, use imperative instructions and concrete decision points.
-
-Include:
-- quick-start flow
-- fallback path for common failures
-- output formatting expectations
-- minimal examples
+```yaml
+description: "[What — 1 sentence]. Use when [context]. Also use when the user mentions '[phrase1],' '[phrase2],' ... [For X, see other-skill.]"
+```
 
-Avoid:
-- tool/vendor lock-in unless explicitly required
-- long conceptual explanations without action
-- hidden assumptions about environment
+## Step 2: Choose Structure
 
-### 6. Validate before shipping
+**Standalone** — single workflow, under ~300 lines total.
+**Router** — multiple modes, combined >300 lines, user may not know which mode they need.
 
-Run this checklist:
+For detailed structure patterns with examples, see [references/patterns.md](references/patterns.md).
 
-- Metadata is clear and triggerable.
-- Instructions are executable end-to-end.
-- Optional resources are referenced from `SKILL.md`.
-- Examples are realistic and match expected outputs.
-- No unnecessary files (README, changelog, process notes).
-- No conflicting or duplicated guidance.
+## Step 3: Write the Body
 
-### 7. Iterate from real usage
+**Process in SKILL.md, knowledge in references.** Keep body under 500 lines.
 
-After first use:
-- note where the agent hesitated or failed
-- tighten trigger text and decision points
-- move repeated logic into scripts/templates
-- keep the file lean as capability grows
+For standalone skills — imperative steps with decision points:
+```markdown
+## Workflow
+1. [Action]
+2. [Decision — if X do A, if Y do B]
+3. [Output]
+```
 
-## Portable Skill Template
+For router skills — just a routing table:
+```markdown
+## Mode Selection
+| Task | File |
+|------|------|
+| Task A | [mode-a.md](mode-a.md) |
+| Task B | [mode-b.md](mode-b.md) |
+```
 
-Use this starter when creating a new skill:
+References one level deep only. Every reference linked from SKILL.md with "when to read" context.
 
-```markdown
----
-name: your-skill-name
-description: What this skill does and exactly when to use it.
----
+## Step 4: Cross-reference
 
-## Overview
-One short paragraph on scope and outcome.
+- **Within skill** (router → sub-files): markdown file links — `[mode-a.md](mode-a.md)`
+- **Between skills**: instructional prose — "Invoke the `other-skill` skill"
+- **Shared knowledge**: relative path links — `[ref](../other-skill/references/ref.md)`
 
-## Quick Start
-1. First action.
-2. Main execution path.
-3. Output requirements.
+## Step 5: Validate
 
-## Decision Points
-- If condition A: do X.
-- If condition B: do Y.
-- If blocked: fallback path.
+- [ ] Description: third person, "Use when...", 5+ triggers, negative boundaries, <1024 chars
+- [ ] Body under 500 lines
+- [ ] References linked with "when to read" context, one level deep
+- [ ] Process and knowledge separated
+- [ ] No stale cross-references
+- [ ] If router: routing table clear, sub-files under ~400 lines each
 
-## Resources
-- `scripts/...` for deterministic tasks.
-- `references/...` for detailed docs.
-- `assets/...` for templates and boilerplate.
+## Step 6: Iterate
 
-## Validation
-- Command or checklist to verify output quality.
-```
+After use, observe: Did it trigger correctly? Did the agent load the right content? Tighten description triggers and routing based on what you see.
 
-## Editing an Existing Skill
+## Editing Existing Skills
 
-When updating a skill:
-- preserve existing behavior unless intentionally changing it
-- document new triggers in description
-- remove stale instructions immediately
-- keep backward-compatible structure when possible
+- Preserve behavior unless intentionally changing
+- Update description if scope changed
+- If over 500 lines → convert to router
+- If pure knowledge with no workflow → demote to reference file
 
-## Output Standard
+## References
 
-A finished skill should be:
-- discoverable (clear trigger description)
-- executable (step-by-step, no ambiguity)
-- maintainable (small core, reusable resources)
-- portable (minimal runtime-specific assumptions)
+- [Architecture Patterns](references/patterns.md) — progressive disclosure tiers, standalone vs router vs shared reference patterns, merge heuristics, description examples across domains, anti-patterns. Read this when choosing structure or writing descriptions.

package/skills/agent-skill-creator/references/patterns.md

@@ -0,0 +1,178 @@
+# Skill Architecture Patterns
+
+Concrete patterns for structuring skills. Examples use generic domains — adapt to your context.
+
+---
+
+## Progressive Disclosure
+
+Skills load in three tiers:
+
+| Tier | What | When | Cost |
+|---|---|---|---|
+| L1: Metadata | name + description | Session start | ~50-100 tokens/skill |
+| L2: Body | SKILL.md content | When triggered | ~500-2000 tokens |
+| L3: Resources | references/, scripts/, sub-files | On demand | Variable |
+
+Design accordingly: routing decisions in L2, detailed knowledge in L3. The description (L1) is always loaded — it's the only thing that determines whether L2 ever loads.
+
+---
+
+## Pattern 1: Standalone
+
+Single-purpose skill, one file.
+
+```
+deploy-checker/
+├── SKILL.md          # Full workflow (~150 lines)
+└── references/
+    └── provider-configs.md
+```
+
+**Use when:** One workflow, under ~300 lines. Examples: CLI references, simple tools, single-process skills.
+
+---
+
+## Pattern 2: Router
+
+Multiple related modes behind one entry point.
+
+```
+code-review/
+├── SKILL.md              # Router (~25 lines)
+├── pr-review.md          # Full PR review workflow
+├── pre-landing.md        # Pre-merge safety checks
+```
+
+**Router body is just a routing table:**
+```markdown
+| Task | File |
+|------|------|
+| General PR review | [pr-review.md](pr-review.md) |
+| Pre-merge safety check | [pre-landing.md](pre-landing.md) |
+```
+
+**Use when:**
+- Domain has 2+ related workflows
+- Combined content would exceed ~300 lines
+- User may not know which mode they need
+
+**How it helps:** Collapses N L1 entries into 1. Routing moves from L1 (scan all descriptions) to L2 (read one body). Only the relevant mode's content loads.
+
+---
+
+## Pattern 3: Shared References
+
+Knowledge file used by multiple skills.
+
+```
+skill-a/
+└── references/
+    └── shared-principles.md    ← lives here
+
+skill-b/SKILL.md references:
+  ../skill-a/references/shared-principles.md
+
+skill-c/SKILL.md references:
+  ../skill-a/references/shared-principles.md
+```
+
+**Use when:** Multiple skills need the same domain knowledge. Put it in one place, link from others. Avoids duplication and drift.
+
+---
+
+## Pattern 4: Shared Data Layer
+
+One skill creates context that many others consume.
+
+```
+context-builder/
+└── SKILL.md    # Creates .agents/project-context.md
+
+# Many other skills check for this file:
+## Before Starting
+If `.agents/project-context.md` exists, read it first.
+```
+
+**Use when:** Foundational context that prevents multiple skills from asking the same setup questions. Product info, org context, project state.
+
+---
+
+## Pattern 5: Knowledge Demotion
+
+Convert a knowledge catalog (no workflow) into a reference file.
+
+**Before** — standalone skill nobody directly invokes:
+```
+cognitive-biases/
+└── SKILL.md          # 450 lines of reference material, no workflow
+```
+
+**After** — reference file linked from process skills:
+```
+persuasion-skill/references/cognitive-biases.md
+```
+
+**Rule:** If a skill has no imperative steps — no "Step 1, Step 2" — it's knowledge, not a skill. Make it a reference.
+
+---
+
+## Merge Heuristic
+
+**Keep standalone if ANY is true:**
+- Unique trigger phrase ("deploy to production" ≠ "review this PR")
+- Specific tool/runtime dependency
+- Distinct deliverable type
+- Foundational pre-step for other skills
+
+**Merge into router if ALL are true:**
+- Same domain (user thinks of them as one thing)
+- Same input shape (same context needed)
+- User often unsure which sub-skill they need
+- Each sub-skill under ~400 lines
+
+---
+
+## Description Examples
+
+Diverse examples across domains:
+
+**CLI tool:**
+```yaml
+description: "Terraform CLI reference and common workflows for plan, apply, state management, workspaces, and module development. Use when the user asks about terraform commands, infrastructure as code, or IaC workflows."
+```
+
+**Engineering process:**
+```yaml
+description: "Review pull requests and code diffs for correctness, design, security, performance, and style. Use when asked to 'review this PR,' 'review my changes,' 'check this diff,' or before merging code."
+```
+
+**Creative/marketing:**
+```yaml
+description: "Write marketing copy for landing pages, homepages, feature pages, and product pages. Use when the user says 'write copy,' 'headline help,' 'CTA copy,' or 'make this more compelling.' For email copy, see the email skill."
+```
+
+**Router:**
+```yaml
+description: "Unified plan review with CEO, engineering, and minimalist lenses. Use when reviewing a plan, strategy, or decision. Triggers: 'review my plan,' 'gut-check this,' 'is this too complex,' 'engineering review.'"
+```
+
+**Data/context:**
+```yaml
+description: "Create or update the product marketing context document that other skills use. Use when starting a new project, setting up positioning, defining ICP, or when other skills keep asking the same context questions."
+```
+
+---
+
+## Anti-Patterns
+
+| Problem | Why it fails | Fix |
+|---|---|---|
+| Vague description | Low activation rate | Add "Use when..." with 5+ trigger phrases |
+| 500+ line monolith | Context bloat | Split into router + sub-files |
+| Knowledge as standalone skill | Nobody invokes a reference catalog | Demote to reference file |
+| Nested references (A → B → C) | Agent may partially read nested files | One level deep only |
+| Duplicate content across SKILL.md and references | Token waste, drift risk | Process in SKILL.md, knowledge in references |
+| First-person description | Breaks discovery (injected into system prompt) | Always third person |
+| No negative boundaries | Triggers for wrong tasks | Add "For X, see Y instead" |
+| Domain-specific examples in a generic skill | Confuses users from other domains | Use diverse examples |

package/skills/asc-cli/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: asc-cli
+description: Use this skill for App Store Connect CLI (`asc`) usage, including install/auth setup, command families, CI/CD integration, and troubleshooting for releases, builds, TestFlight, metadata, signing, finance, and analytics workflows.
+---
+
+# App Store Connect CLI (`asc`)
+
+Use this skill when the user asks about `asc` CLI command usage, automation patterns, CI/CD, or which `asc` command to run for a release workflow.
+
+## Quick setup
+
+1. Install `asc`:
+
+```bash
+# Recommended
+brew install asc
+
+# macOS/Linux fallback
+curl -fsSL https://asccli.sh/install | bash
+```
+
+2. Verify installation:
+
+```bash
+asc --help
+asc --version
+```
+
+3. Authenticate:
+
+```bash
+asc auth login \
+  --name "MyApp" \
+  --key-id "ABC123" \
+  --issuer-id "DEF456" \
+  --private-key /path/to/AuthKey.p8
+```
+
+For Apple API credentials, generate key details at:
+https://appstoreconnect.apple.com/access/integrations/api
+
+## Core command families
+
+Use `asc <command> --help` for current flags and nested subcommands.
+
+- `auth` — authentication and profile management.
+- `doctor` — diagnose config/auth issues.
+- `install-skills` — install asc skill pack for prebuilt workflows.
+- `init` — initialize asc helper docs in repo.
+- `docs` — open embedded documentation helpers.
+- `analytics` — report and sales analytics.
+- `insights` — weekly/daily insights.
+- `finance` — financial and payout reports.
+- `performance` — performance diagnostics.
+- `feedback`, `crashes` — TestFlight feedback/crash discovery.
+- `apps`, `app-info`, `versions`, `localizations` — app metadata lifecycle.
+- `app-setup`, `app-tags`, `app-clips`, `android-ios-mapping` — setup and platform mappings.
+- `screenshots`, `video-previews`, `background-assets`, `product-pages` — visual metadata assets.
+- `builds`, `build-bundles`, `pre-release-versions` — binary build operations.
+- `testflight`, `beta-app-localizations`, `beta-build-localizations`, `sandbox` — TestFlight workflows.
+- `submit`, `validate`, `publish` — review/release workflows.
+- `review`, `reviews` — review artifacts and customer reviews.
+- `iap`, `subscriptions`, `offer-codes`, `app-events` — monetization workflows.
+- `signing`, `certificates`, `profiles`, `bundle-ids`, `merchant-ids`, `pass-type-ids` — signing and identifiers.
+- `notarization` — macOS notarization flow.
+- `users`, `devices`, `account`, `actors` — team and access management.
+- `xcode-cloud` — trigger and monitor Xcode Cloud runs.
+- `webhooks`, `notify` — events and integrations.
+- `workflow`, `status`, `metadata`, `diff`, `release-notes` — automation and planning utilities.
+
+## Common practical commands
+
+- List apps:
+
+```bash
+asc apps list --output table
+```
+
+- Upload a build:
+
+```bash
+asc builds upload --app "123456789" --file "/path/to/MyApp.ipa"
+```
+
+- Validate and submit:
+
+```bash
+asc validate --app "123456789" --version "1.2.3"
+asc submit --app "123456789" --version "1.2.3"
+```
+
+- Pull TestFlight feedback and crashes:
+
+```bash
+asc feedback --app "123456789" --paginate
+asc crashes --app "123456789" --sort -createdDate --limit 25
+```
+
+- Run a defined workflow:
+
+```bash
+asc workflow run --file .asc/workflow.json --workflow release
+```
+
+## Scripting and CI practices
+
+- Use deterministic output:
+  - `--output json` (default, machine-friendly, minified)
+  - `--output table|markdown` for humans
+  - `--paginate` to fetch all pages
+- CI reporting:
+  - `--report` (example `junit`)
+  - `--report-file` to save artifacts.
+- Multi-profile CI:
+  - `asc --profile production ...`
+  - Use explicit `--app`, `--limit`, `--paginate` for stable scripting.
+- Auth in non-interactive CI:
+  - Prefer `asc auth login --name ...` with secure secret handling and reuse stored profile.
+
+## Troubleshooting and useful patterns
+
+- "No guessing of flags": check help first (`asc <command> --help`).
+- "No prompt surprises": for destructive writes, prefer `--confirm`.
+- Error-heavy operations in scripts: pin exact versions and verify return codes.
+- Apple quirks and API notes: https://github.com/rudrankriyam/App-Store-Connect-CLI/blob/main/docs/API_NOTES.md
+
+## Non-official caveat
+
+This project is unofficial and not affiliated with Apple. Confirm risk acceptance before replacing official tooling.
+
+## Official references
+
+- https://github.com/rudrankriyam/App-Store-Connect-CLI
+- https://github.com/rudrankriyam/App-Store-Connect-CLI/blob/main/README.md
+- https://github.com/rudrankriyam/App-Store-Connect-CLI/blob/main/docs/COMMANDS.md
+- https://github.com/rudrankriyam/App-Store-Connect-CLI/blob/main/docs/CI_CD.md
+- https://github.com/rudrankriyam/App-Store-Connect-CLI/blob/main/docs/API_NOTES.md
+- https://github.com/rudrankriyam/App-Store-Connect-CLI/blob/main/AGENTS.md
+- https://github.com/rudrankriyam/App-Store-Connect-CLI/releases
+- https://asccli.sh/
+- https://github.com/rudrankriyam/app-store-connect-cli-skills