Implement devotee player commands — followers, assign, dismiss, recruit #220

New issue

Open

opened 2026-03-16 01:39:09 +00:00 by freemo · 0 comments

freemo commented

2026-03-16 01:39:09 +00:00

Owner

Metadata

Field	Value
Epic	#203 — Devotee System
Legendary	#199 — Reputation & Social Standing
Type	Feature
Priority	Medium
Points	8
MoSCoW	Must Have
Branch	`feature/m4-devotee-player-commands`
Commit Message	`Implement devotee player commands — followers, assign, dismiss, recruit (#220)`

Background and Context

Players need commands to interact with the Devotee system. This issue implements four core player commands: followers to view current devotees, assign to give a devotee a task, dismiss to release a devotee, and recruit to convert a willing NPC into a devotee.

Recruitment is gated by reputation — a player must have at least Respected tier standing with the NPC's faction to recruit them. This creates a meaningful connection between the reputation system and the devotee system, rewarding players who invest in building faction relationships.

All commands follow the existing Aethyr command pattern and integrate with the command parser system.

Expected Behavior

followers: Lists all current devotees in a formatted table showing name, specialty, skill level, current assignment (or "Idle"), loyalty, and morale. Shows a summary count.
assign <name> <task>: Sets the named devotee's assignment to the specified task. Validates that the devotee exists, belongs to the player, and the task is valid for their specialty. Provides confirmation message.
dismiss <name>: Removes the named devotee from the player's devotee list. The NPC returns to their original location. Requires confirmation. Provides feedback message.
recruit <npc>: Attempts to recruit the targeted NPC as a devotee.
- Checks the NPC is recruitible (has recruitible: true flag).
- Checks player reputation with NPC's faction is >= Respected tier.
- Checks player has not exceeded their devotee cap (based on reputation tier).
- On success: creates a DevoteeNPC from the NPC, adds to player's devotees, displays success message.
- On failure: displays appropriate error message (not recruitible, insufficient reputation, cap reached).

Acceptance Criteria

followers command displays a formatted table of all devotees with all fields.
followers shows "You have no followers" when the list is empty.
assign <name> <task> correctly assigns a task to a devotee.
assign rejects invalid devotee names with an error message.
assign rejects tasks that don't match the devotee's specialty.
dismiss <name> removes the devotee and returns the NPC.
dismiss rejects invalid devotee names with an error message.
recruit <npc> succeeds when all conditions are met.
recruit fails with appropriate message when NPC is not recruitible.
recruit fails with appropriate message when reputation is too low.
recruit fails with appropriate message when devotee cap is reached.
All commands are registered in the command parser.

Subtasks

Create lib/aethyr/core/commands/followers.rb with the followers command handler.
Implement formatted devotee listing with all fields.
Create lib/aethyr/core/commands/assign.rb with the assign command handler.
Implement assignment validation (devotee exists, task matches specialty).
Create lib/aethyr/core/commands/dismiss.rb with the dismiss command handler.
Implement devotee removal and NPC restoration.
Create lib/aethyr/core/commands/recruit.rb with the recruit command handler.
Implement recruitment checks (recruitible flag, reputation tier, devotee cap).
Register all commands in the command parser.
Implement error and success messages for all commands.
Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/devotee_commands.feature covering all four commands with success cases, error cases, edge cases, and formatted output.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for end-to-end devotee management including recruitment, assignment, and dismissal flows.
Tests (Profiling): Run bundle exec rake unit_profile and verify no performance regressions.
Quality: Verify coverage >=97% via bundle exec rake unit. If coverage is <97% then review the current unit test coverage report at build/tests/unit/coverage/ and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun bundle exec rake unit to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
Quality: Run bundle exec rake (default task: unit tests with coverage) and bundle exec rake integration, fix any errors if needed ensuring both pass across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Field | Value | |-------|-------| | **Epic** | #203 — Devotee System | | **Legendary** | #199 — Reputation & Social Standing | | **Type** | Feature | | **Priority** | Medium | | **Points** | 8 | | **MoSCoW** | Must Have | | **Branch** | `feature/m4-devotee-player-commands` | | **Commit Message** | `Implement devotee player commands — followers, assign, dismiss, recruit (#220)` | ## Background and Context Players need commands to interact with the Devotee system. This issue implements four core player commands: `followers` to view current devotees, `assign` to give a devotee a task, `dismiss` to release a devotee, and `recruit` to convert a willing NPC into a devotee. Recruitment is gated by reputation — a player must have at least Respected tier standing with the NPC's faction to recruit them. This creates a meaningful connection between the reputation system and the devotee system, rewarding players who invest in building faction relationships. All commands follow the existing Aethyr command pattern and integrate with the command parser system. ## Expected Behavior 1. **`followers`**: Lists all current devotees in a formatted table showing name, specialty, skill level, current assignment (or "Idle"), loyalty, and morale. Shows a summary count. 2. **`assign <name> <task>`**: Sets the named devotee's assignment to the specified task. Validates that the devotee exists, belongs to the player, and the task is valid for their specialty. Provides confirmation message. 3. **`dismiss <name>`**: Removes the named devotee from the player's devotee list. The NPC returns to their original location. Requires confirmation. Provides feedback message. 4. **`recruit <npc>`**: Attempts to recruit the targeted NPC as a devotee. - Checks the NPC is recruitible (has `recruitible: true` flag). - Checks player reputation with NPC's faction is >= Respected tier. - Checks player has not exceeded their devotee cap (based on reputation tier). - On success: creates a DevoteeNPC from the NPC, adds to player's devotees, displays success message. - On failure: displays appropriate error message (not recruitible, insufficient reputation, cap reached). ## Acceptance Criteria - [ ] `followers` command displays a formatted table of all devotees with all fields. - [ ] `followers` shows "You have no followers" when the list is empty. - [ ] `assign <name> <task>` correctly assigns a task to a devotee. - [ ] `assign` rejects invalid devotee names with an error message. - [ ] `assign` rejects tasks that don't match the devotee's specialty. - [ ] `dismiss <name>` removes the devotee and returns the NPC. - [ ] `dismiss` rejects invalid devotee names with an error message. - [ ] `recruit <npc>` succeeds when all conditions are met. - [ ] `recruit` fails with appropriate message when NPC is not recruitible. - [ ] `recruit` fails with appropriate message when reputation is too low. - [ ] `recruit` fails with appropriate message when devotee cap is reached. - [ ] All commands are registered in the command parser. ## Subtasks - [ ] Create `lib/aethyr/core/commands/followers.rb` with the `followers` command handler. - [ ] Implement formatted devotee listing with all fields. - [ ] Create `lib/aethyr/core/commands/assign.rb` with the `assign` command handler. - [ ] Implement assignment validation (devotee exists, task matches specialty). - [ ] Create `lib/aethyr/core/commands/dismiss.rb` with the `dismiss` command handler. - [ ] Implement devotee removal and NPC restoration. - [ ] Create `lib/aethyr/core/commands/recruit.rb` with the `recruit` command handler. - [ ] Implement recruitment checks (recruitible flag, reputation tier, devotee cap). - [ ] Register all commands in the command parser. - [ ] Implement error and success messages for all commands. - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/devotee_commands.feature` covering all four commands with success cases, error cases, edge cases, and formatted output. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for end-to-end devotee management including recruitment, assignment, and dismissal flows. - [ ] Tests (Profiling): Run `bundle exec rake unit_profile` and verify no performance regressions. - [ ] Quality: Verify coverage >=97% via `bundle exec rake unit`. If coverage is <97% then review the current unit test coverage report at `build/tests/unit/coverage/` and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `bundle exec rake unit` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Quality: Run `bundle exec rake` (default task: unit tests with coverage) and `bundle exec rake integration`, fix any errors if needed ensuring both pass across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.